Docs
-->
Elasticsearch Reference [7.0] » X-Pack APIs » Machine learning APIs » Get overall buckets API
«  Get buckets API     Get categories API  »

Get overall buckets API

Retrieves overall bucket results that summarize the bucket results of multiple jobs.

Request

GET _ml/anomaly_detectors/<job_id>/results/overall_buckets

GET _ml/anomaly_detectors/<job_id>,<job_id>/results/overall_buckets

GET _ml/anomaly_detectors/_all/results/overall_buckets

Description

You can summarize the bucket results for all jobs by using _all or by specifying * as the <job_id>.

An overall bucket has a span equal to the largest bucket_span value for the specified jobs.

The overall_score is calculated by combining the scores of all the buckets within the overall bucket span. First, the maximum anomaly_score per job in the overall bucket is calculated. Then the top_n of those scores are averaged to result in the overall_score. This means that you can fine-tune the overall_score so that it is more or less sensitive to the number of jobs that detect an anomaly at the same time. For example, if you set top_n to 1, the overall_score is the maximum bucket score in the overall bucket. Alternatively, if you set top_n to the number of jobs, the overall_score is high only when all jobs detect anomalies in that overall bucket.

In addition, the optional parameter bucket_span may be used in order to request overall buckets that span longer than the largest job’s bucket_span. When set, the overall_score will be the max overall_score of the corresponding overall buckets with a span equal to the largest job’s bucket_span.

Path Parameters

job_id
(string) Identifier for the job. It can be a job identifier, a group name, a comma-separated list of jobs or groups, or a wildcard expression.

Request Body

allow_no_jobs
(boolean) If false and the job_id does not match any job an error will be returned. The default value is true.
bucket_span
(string) The span of the overall buckets. Must be greater or equal to the largest job’s bucket_span. Defaults to the largest job’s bucket_span.
end
(string) Returns overall buckets with timestamps earlier than this time.
exclude_interim
(boolean) If true, the output excludes interim overall buckets. Overall buckets are interim if any of the job buckets within the overall bucket interval are interim. By default, interim results are included.
overall_score
(double) Returns overall buckets with overall scores greater or equal than this value.
start
(string) Returns overall buckets with timestamps after this time.
top_n
(integer) The number of top job bucket scores to be used in the overall_score calculation. The default value is 1.

Results

The API returns the following information:

overall_buckets
(array) An array of overall bucket objects. For more information, see Overall Buckets.

Authorization

You must have monitor_ml, monitor, manage_ml, or manage cluster privileges to use this API. You also need read index privilege on the index that stores the results. The machine_learning_admin and machine_learning_user roles provide these privileges. For more information, see Security Privileges and Built-in Roles.

Examples

The following example gets overall buckets for jobs with IDs matching job-*:

GET _ml/anomaly_detectors/job-*/results/overall_buckets
{
  "overall_score": 80,
  "start": "1403532000000"
}

In this example, the API returns a single result that matches the specified score and time constraints. The overall_score is the max job score as top_n defaults to 1 when not specified:

{
  "count": 1,
  "overall_buckets": [
    {
      "timestamp" : 1403532000000,
      "bucket_span" : 3600,
      "overall_score" : 80.0,
      "jobs" : [
        {
          "job_id" : "job-1",
          "max_anomaly_score" : 30.0
        },
        {
          "job_id" : "job-2",
          "max_anomaly_score" : 10.0
        },
        {
          "job_id" : "job-3",
          "max_anomaly_score" : 80.0
        }
      ],
      "is_interim" : false,
      "result_type" : "overall_bucket"
    }
  ]
}

The next example is similar but this time top_n is set to 2:

GET _ml/anomaly_detectors/job-*/results/overall_buckets
{
  "top_n": 2,
  "overall_score": 50.0,
  "start": "1403532000000"
}

Note how the overall_score is now the average of the top 2 job scores:

{
  "count": 1,
  "overall_buckets": [
    {
      "timestamp" : 1403532000000,
      "bucket_span" : 3600,
      "overall_score" : 55.0,
      "jobs" : [
        {
          "job_id" : "job-1",
          "max_anomaly_score" : 30.0
        },
        {
          "job_id" : "job-2",
          "max_anomaly_score" : 10.0
        },
        {
          "job_id" : "job-3",
          "max_anomaly_score" : 80.0
        }
      ],
      "is_interim" : false,
      "result_type" : "overall_bucket"
    }
  ]
}
«  Get buckets API     Get categories API  »