Home

Detect anomalies on univariate time series data

You can use this API to detect anomalies in any time series data (date-time and metrics value). For example, you can pass metric values such as the duration of a job or query, input/output values, CPU usage, and so on. Then, the API locates anomalies in the specified metrics and returns anomalous data.

Request

The request produces an application/json payload.

POST http://<unravel-host>/api/v1/app_store/api/v1/anomalies/time-series/

Example: http://<unravel_host>/api/v1/app_store/api/v1/anomalies/time-series/

Note

You must pass the time-series data manually in the request. See Examples

Path parameters

None

Query parameters

All the parameters are optional.

Name

Type

Description

tolerance

integer

Controls the anomaly boundaries—the lower the tolerance, the lower the interval width.

Default value: 0.95

lowerBoundary

upperBoundary

float

Returns anomaly results with upper and lower anomaly detection boundaries. You can use these values to visualize the range of expected values and anomalies in the data.

Examples:

  • When lowerBoundary=5 and upperBoundary=None, all values greater than five are returned as not anomalies.

  • When lowerBoundary=None and upperBoundary=100, all values lower than 100 are returned as not anomalies.

  • When lowerBoundary=10 and upperBoundary=100, all values between 10 and 100 are returned as not anomalies.

  • When lowerBoundary=None and upperBoundary=None, it returns all anomalies reported by the algorithm.

Default value: None

topNAnomalies

integer

Displays the highest ten anomalies based on the significance. This parameter is ignored if the algorithm returns greater than the number of anomalies reported.

Default value: None

returnAnomaliesOnly

boolean

  • True: Returns only anomalies, not all the data points.

  • False: Returns all data points.

Default value: True

suppressNegativeAnomalies

boolean

  • True: Returns all anomalies.

  • False: Suppresses negative anomalies. If the values are lower than the value specified for the lowerBoundary parameter, those values are considered negative anomalies. These negative anomalies are not returned in the output.

Default value: False

Examples

Request 

{
   "2022-03-07T14:10:26.054Z": 145.81,
   "2022-03-07T18:58:27.724Z": 98.19,
   "2022-03-07T21:51:45.795Z": 2.33
}

Response

[
    {
        "value": 1003.68,
        "anomaly": 1,
        "datetime": "2022-03-07T14:10:26.054Z",
        "lowerBoundary": -353.0971368821741,
        "upperBoundary": 211.2440259262434,
        "score": 3.7512822935425327
    },
    {
        "value": 892.88,
        "anomaly": 1,
        "datetime": "2022-03-07T18:58:27.724Z",
        "lowerBoundary": -342.4256825972108,
        "upperBoundary": 215.2033326724421,
        "score": 3.14900637881403
    },
    {
        "value": 8.74,
        "anomaly": 0,
        "datetime": "2022-03-08T11:32:27.724Z",
        "lowerBoundary": -312.14910623307986,
        "upperBoundary": 233.95741058128132,
        "score": 0.0
    }
]

Other than the input parameter values, the response returns the following additional parameters:

  • anomaly: Indicates the type of anomaly. The value is an integer.

    • Returns 1 if it is a positive anomaly.

    • Returns -1 if it is a negative anomaly.

    • Returns 0 if it is not an anomaly or when the value for the returnAnomaliesOnly parameter is False in the request.

  • score: Returns the score for each anomaly. The score indicates how far the data points away from the boundary. The farther the value from its boundary, the higher the score.

In this section: