Trend Detections

Owned by Patrice Neff
Last updated: Feb 28, 2018 by Oliver Seeliger (Unlicensed)
6 min read

Trend Detection is configured on projects to look for anomalies in time series data. For an introduction and tutorial on this feature, read the Trend Detection chapter.

Methods

List Trend Detection Entities

GET https://squirro-endpoint/api/topic/v0/(string: tenant)/projects/(id: project_id)/trenddetections

Returns an array of all trend detection entities in a project.

Parameters:
  • tenant – User tenant.
  • project_id – Project identifier.
Headers:See Common Headers.
Status Codes:
  • 200 – All trend detection entities are returned.

See also Common Status Codes.

Returns:

List of configured trend detection entities.

{
    "trend_detection_entities": [
        {
            "aggregation_time_field": "$item_created_at", 
            "aggregation_field": "Price", 
            "name": "EU Egg Price Trend", 
            "created_at": "2016-06-07T10:52:05", 
            "modified_at": "2016-06-07T10:52:07",
			"trends_healthy": True, 
            "aggregation_interval": "1w", 
            "aggregation_method": "avg", 
            "query": "Type:\"Egg Price\" \"Country\":EU", 
            "project_id": "j0mN4DgQTGWDSBP3QcqDwg", 
            "id": "em_I-hJMRzi-OjvObOqU6A"
        }
    ]
}
  • In the output response, `trends_healthy` is a boolean parameter which signifies whether or not
    the last retraining of the current trend-detection entity has been successful or not.

Create Trend Detection Entity

POST https://squirro-endpoint/api/topic/v0/(string: tenant)/projects/(id: project_id)/trenddetections

Parameters:
  • tenant – User tenant.
  • project_id – Project identifier.
JSON Data:

Data is passed in as a JSON object.

Valid object keys:

  • name (required) – Human-readable name of the trend detection entity.
  • query (required) – The query on which the trend is analyzed. The query may be an empty string, in which case all items in the project are analyzed.
  • email_user (required) – Email address to send an alert to when an anomaly is detected.
  • aggregation_interval (required) – Determines the time buckets into which the data is fitted.
    The format of the interval is "<number><unit>" - for example "1d" for a daily interval. The full list of allowed units is "m" - minute, "h" - hour , "d" - day, "w" - week.
    See the Aggregation Interval reference for full details on this parameter.
  • aggregation_field – Facet field on which to detect the trends. If this is not specified, the trend is computed on the number of results in a time frame.
  • aggregation_method – Aggregation method on how the numeric values are combined. Only used if aggregation_field is set too.
    Valid options: avg (default), sum, max, min.
    See the Aggregation Method reference for full details on this parameter.
  • aggregation_time_field – Datetime facet field on which axis to calculate the trend. This defaults to $item_created_at.
Headers:See Common Headers.
Status Codes:
  • 201 – Trend detection entity created.

See also Common Status Codes.

Returns:

Created trend detection.

{
	"trend_detection_entity": {
    	"aggregation_time_field": "$item_created_at", 
    	"aggregation_field": "Price", 
    	"name": "EU Egg Price Trend", 
    	"created_at": "2016-06-15T11:15:46", 
    	"modified_at": "2016-06-15T11:15:46", 
		"trends_healthy": True,
    	"aggregation_interval": "1d", 
    	"aggregation_method": "avg", 
    	"query": "Type:\"Egg Price\" \"Country\":EU", 
    	"project_id": "V73xio3rR6-8lPwBOG_EVA", 
    	"id": "hI9E58PvT_mTPtpC6_rQkQ"
	} 
}
  • In the output response, `trends_healthy` is a boolean parameter which signifies whether or not the last retraining of the current trend-detection entity has been successful or not.

Get Trend Detection Entity

GET https://squirro-endpoint/api/topic/v0/(string: tenant)/projects/(id: project_id)/trenddetections/(id: tde_id)

Parameters:
  • tenant – User tenant.
  • project_id – Project identifier.
  • tde_id – Trend Detection Entity identifier.
  • include_trend_detection_entity – Boolean flag to include the trend detection entity parameters in the response. Defaults to True if not specified.
  • include_thresholds – Boolean flag to include the thresholds corresponding of the trend detection entity in the response. Defaults to False if not specified.
  • include_anomalies – Boolean flag to include the detected anomalies of the trend detection entity in the response. Defaults to False if not specified.
  • include_predictions – Boolean flag to include the predictions and the corresponding threholds of the trend detection entity. Defaults to False if not specified.
  • result_before – A Datetime type string to limit the time series data returned to be strictly before the result_before timestamp. If not specified, defaults to no end date restrictions for the returned data.
  • result_after – A Datetime type string to limit the time series data returned to be strictly after the result_after timestamp. If not specified, defaults to no start date restrictions for the returned data.
Headers:See Common Headers.
Status Codes:
  • 200 – Trend Detection Entity returned.

See also Common Status Codes.

Returns:

Requested Trend Detection Entity.

{
	"trend_detection_entity": {
    	"aggregation_time_field": "$item_created_at", 
    	"aggregation_field": "Price", 
    	"name": "EU Egg Price Trend", 
    	"created_at": "2016-06-15T11:15:46", 
    	"modified_at": "2016-06-15T11:15:46",
		"trends_healthy": True,
    	"aggregation_interval": "1d", 
    	"aggregation_method": "avg", 
    	"query": "Type:\"Egg Price\" \"Country\":EU", 
    	"project_id": "V73xio3rR6-8lPwBOG_EVA", 
    	"id": "hI9E58PvT_mTPtpC6_rQkQ"
	}
}
  • In the output response, `trends_healthy` is a boolean parameter which signifies whether or not the last retraining of the current trend-detection entity has been successful or not.

Delete Trend Detection Entity

DELETE https://squirro-endpoint/api/topic/v0/(string: tenant)/projects/(id: project_id)/trenddetections/(id: tde_id)

Parameters:
  • tenant – User tenant.
  • project_id – Project identifier.
  • tde_id – Trend Detection Entity identifier.
Headers:

See Common Headers.

Status Codes:
  • 204 – Trend Detection Entity deleted.

See also Common Status Codes.



Method deprecations

Methods below will be deprecated soon. Please use the boolean flags with `Get Trend Detection Entity` end point to get the thresholds, labels and predictions.


Get Thresholds

GET https://squirro-endpoint/api/topic/v0/(string: tenant)/projects/(id: project_id)/trenddetections/{id: tde_id}/thresholds

Returns a list of the calculated thresholds for dates in the trend detection time range. Based on these thresholds the anomalies are flagged - every time the data surpasses the threshold, it's an anomaly.

In the trend detection widget on the dashboard, the thresholds are visualized with the grey background area.

Parameters:
  • tenant – User tenant.
  • project_id – Project identifier.
  • tde_id – Trend Detection Entity identifier.
Query Parameters:

Parameters are optional.

Headers:See Common Headers.
Status Codes:
  • 200 – Thresholds returned.

See also Common Status Codes.

Returns:

List of Thresholds.

{
    "thresholds": [
        {
            "count": 127.8694520548, 
            "timestamp": "2015-01-05T00:00:00"
        }, 
        {
            "count": 126.9704256148, 
            "timestamp": "2015-01-12T00:00:00"
        }, 
        {
            "count": 126.2358246885, 
            "timestamp": "2015-01-19T00:00:00"
        }, 
        {
            "count": 125.6758949924, 
            "timestamp": "2015-01-26T00:00:00"
        }
    ]
}

Get Labels

GET https://squirro-endpoint/api/topic/v0/(string: tenant)/projects/(id: project_id)/trenddetections/{id: tde_id}/labels

Returns the detected labels (anomalies) in the data.

Parameters:
  • tenant – User tenant.
  • project_id – Project identifier.
  • tde_id – Trend Detection Entity identifier.
Query Parameters:

Parameters are optional.

Headers:See Common Headers.
Status Codes:
  • 200 – Labels returned.

See also Common Status Codes.

Returns:

List of Labels.

{
    "labels": [
        "2015-04-06T00:00:00"
    ]
}

This output signifies that the data contains one anomaly in the data, namely in the aggregation interval that starts on 2015-04-06 midnight.

Get Predictions

GET https://squirro-endpoint/api/topic/v0/(string: tenant)/projects/(id: project_id)/trenddetections/{id: tde_id}/predictions

Returns the future predicted thresholds for the given Trend Detection Entity. This returns predictions for the same time range on which data has been processed already.

Parameters:
  • tenant – User tenant.
  • project_id – Project identifier.
  • tde_id – Trend Detection Entity identifier.
Headers:See Common Headers.
Status Codes:
  • 200 – Thresholds returned.

See also Common Status Codes.

Returns:

List of Predictions.

The example output below has been cut.

{
    "predictions": [
        {
            "timestamp": "2016-02-22T00:00:00", 
            "prediction_value": 8.3393183124, 
            "prediction_threshold": 11.1056841591
        }, 
        {
            "timestamp": "2016-02-29T00:00:00", 
            "prediction_value": 11.9445990546, 
            "prediction_threshold": 12.7986151892
        }
        ]
}

This output shows two time buckets (weekly interval) with a predicted value and the anomaly threshold for each of those buckets.