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. |
---|
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: | 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. |
---|