Get Buckets

Description

Access the result buckets of an analytic job. These may be filtered by date and/or score.

Definition

http://localhost:8080/engine/v2/results/<jobId>/buckets
jobId:The job unique identifier

Parameters

expand:Expand the bucket to include its anomaly records. See Include Anomaly Records.
includeInterim:Include interim results. See Include Interim Results.
anomalyScore:Filter for the most anomalous buckets. See Filter Buckets by Anomaly Score and Normalized Probability.
maxNormalizedProbability:
 Filter for buckets containing the most anomalous records. See Filter Buckets by Anomaly Score and Normalized Probability.
start & end:The start and end times for the request. See Filter Buckets By Date.
skip & take:See Pagination.

Method

GET

Returns

A JSON formatted document containing the results objects for the job instance object of interest. For example, a sample JSON response will take the form:

{
  "hitCount" : 4998,
  "skip" : 0,
  "take" : 100,
  "nextPage" : "http://localhost:8080/engine/v2/results/job001/buckets?skip=100&take=100&expand=false&includeInterim=false&anomalyScore=0.0&maxNormalizedProbability=0.0",
  "previousPage" : null,
  "documents" : [ {
    "timestamp" : "2013-12-21T04:20:00.000+0000",
    "bucketSpan" : 3600,
    "maxNormalizedProbability" : 0.0,
    "anomalyScore" : 0.0,
    "eventCount" : 40,
    "recordCount" : 0,
    "bucketInfluencers": [ ]
  }, {
    "timestamp" : "2013-12-21T04:30:00.000+0000",
    "bucketSpan" : 3600,
    "maxNormalizedProbability" : 0.0,
    "anomalyScore" : 0.0,
    "eventCount" : 40,
    "recordCount" : 0,
    "bucketInfluencers": [ ]
  }, {
  ...
  }
}

Include Anomaly Records

Append the ?expand=true query parameter the request URL and the bucket’s anomaly records will appear nested in the bucket under the records field.

This can be applied to all buckets:

http://localhost:8080/engine/v2/results/<jobId>/buckets?expand=true

The expanded bucket with nested anomaly records may look like this

{
  "exists" : true,
  "type" : "bucket",
  "document" : {
    "timestamp" : "2014-01-08T08:00:00.000+0000",
    "bucketSpan" : 3600,
    "maxNormalizedProbability" : 100.0,
    "anomalyScore" : 100.0,
    "bucketInfluencers": [ {
      "probability": 5.12332E-244,
      "influencerFieldName": "bucketTime",
      "anomalyScore": 100.0
    } ]
    "records" : [ {
      "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
    } ],
    "eventCount" : 39,
    "recordCount" : 1
  }
}

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>/buckets?includeInterim=true

The default is not to include interim results.

Filter Buckets by Anomaly Score and Normalized Probability

Use the anomalyScore and maxNormalizedProbability query parameters to return only those buckets where the score is greater than or equal to a certain value. Please note that the query parameter names are case sensitive.

For example get buckets where anomalyScore >75:

http://localhost:8080/engine/v2/results/<jobId>/buckets?anomalyScore=75

And for maxNormalizedProbability:

http://localhost:8080/engine/v2/results/<jobId>/buckets?maxNormalizedProbability=75

Combine anomalyScore and maxNormalizedProbability filters in the same requrest:

http://localhost:8080/engine/v2/results/<jobId>/buckets?anomalyScore=80&maxNormalizedProbability=75

The anomalyScore and maxNormalizedProbability options can be combined the start and end query parameters.

Filter Buckets By Date

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

http://localhost:8080/engine/v2/results/<jobId>/buckets?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>/buckets?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>/buckets?start=2014-01-22T06:00:00+00:00&end=2014-01-25T06:00:00+00:00
  1. Seconds from the Epoch, for example
http://localhost:8080/engine/v2/results/<jobId>/buckets?start=1390370400&end=1390629600

Note

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

All result buckets 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.

For a detailed description of the output see Bucket 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.