Get Records

Description

Access the results of an analytic job.

The sort and desc query options determine the sort order of the records. Filter out records with an anomalyScore or normalizedProbability below a certain threshold or query over a time range with the start and end options.

Definition

http://localhost:8080/engine/v2/results/<jobId>/records
jobId:The unique identifier of the job.

Parameters

includeInterim:Include interim results. See Include Interim Results.
sort:Sort records by a particular field. See Specifying the Sort Order.
desc:Set the sort direction. See Specifying the Sort Order.
anomalyScore:Filter records by anomaly score. See Filter by anomalousness
normalizedProbability:
 Filter records by normalized probabiltity. See Filter by anomalousness.
start & end:Specify a date range. See Filter Records By Date.
skip & take:See Pagination.

Method

GET

Returns

A JSON formatted document containing the anomaly records for the job of interest. For example, a JSON response will take the form:

{
  "hitCount" : 1332,
  "skip" : 0,
  "take" : 100,
  "nextPage" : "http://localhost:8080/engine/v2/results/job007/records?skip=100&take=100&includeInterim=true&sort=normalizedProbability&desc=true&anomalyScore=0.0&normalizedProbability=0.0",
  "previousPage" : null,
  "documents" : [ {
    "timestamp" : "2014-01-12T12:00:00.000+0000",
    "fieldName" : "value",
    "normalizedProbability" : 100.0,
    "probability" : 2.22507E-308,
    "anomalyScore" : 100.0,
    "function" : "min",
    "typical" : 98.5747,
    "actual" : 68.727,
    "isInterim" : true
  }, {
    "timestamp" : "2014-01-08T08:00:00.000+0000",
    "fieldName" : "value",
    "normalizedProbability" : 100.0,
    "probability" : 2.22507E-308,
    "anomalyScore" : 100.0,
    "function" : "max",
    "typical" : 101.426,
    "actual" : 120.053
  }, {
  ...
  } ]
}

Examples

Include Interim Results

Add the ?includeInterim=true query parameter to include interim results as well as final results.

For example:

http://localhost:8080/engine/v2/results/<jobId>/records?includeInterim=true

The default is not to include interim results.

Specifying the Sort Order

The records can be sorted by any field in ascending or descending order the default is normalizedProbability the most unusual first.

To sort by timestamp in oldest first order:

http://localhost:8080/engine/v2/results/<jobId>/records?sort=timestamp&desc=false

Sort by anomalyScore:

http://localhost:8080/engine/v2/results/<jobId>/records?sort=anomalyScore

Filter by anomalousness

Records can be filtered by anomalyScore and normalizedProbability.

In this example only records with an anomalyScore >75.0 are returned:

http://localhost:8080/engine/v2/results/<jobId>/records?anomalyScore=75.0

and for normalizedProbability a higher threshold is generally used:

http://localhost:8080/engine/v2/results/<jobId>/records?normalizedProbability=98

Filter Records By Date

To return records within a certain time range use the start and end query parameters. For example:

http://localhost:8080/engine/v2/results/<jobId>/records?start=2014-01-22T06:00:00Z&end=2014-01-25T06:00:00Z

Date arguments can be specified using one of three formats:

  1. ISO 8601 format with milliseconds, for example
http://localhost:8080/engine/v2/results/<jobId>/records?start=2014-01-22T06:00:00.000Z&end=2014-01-25T06:00:00.000Z
  1. ISO 8601 format without milliseconds, for example
http://localhost:8080/engine/v2/results/<jobId>/records?start=2014-01-22T06:00:00+05:00&end=2014-01-25T06:00:00+05:00
  1. Seconds from the Epoch, for example
http://localhost:8080/engine/v2/results/<jobId>/records?start=1390370400&end=1390629600

Note that when a URL is expected (e.g. in browsers), the “+” used in time zone designators has to be encoded as “%2B”.

All anomaly records equal to or after the start time and _before_ the end time are returned. Date-time arguments using either of the ISO 8601 formats must have a time zone designator, where Z is accepted as an abbreviation for UTC time.

Putting it all together

Find all anomaly records where normalizedProbability >98 and sort them by date:

curl 'http://localhost:8080/engine/v2/results/<jobId>/records?sort=timestamp&normalizedProbability=98'

For a detailed description of the output see Record Resource, and for details on how to page through a large set of results see Pagination.

Errors

See the Error Codes documentation for the full list of errors that may be returned by the API.