elasticsearch/docs/reference/ml/anomaly-detection/apis/get-overall-buckets.asciidoc

[role="xpack"]
[[ml-get-overall-buckets]]
= Get overall buckets API
++++
<titleabbrev>Get overall buckets</titleabbrev>
++++

Retrieves overall bucket results that summarize the bucket results of multiple
{anomaly-jobs}.

[[ml-get-overall-buckets-request]]
== {api-request-title}

`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`

[[ml-get-overall-buckets-prereqs]]
== {api-prereq-title}

Requires the `monitor_ml` cluster privilege. This privilege is included in the 
`machine_learning_user` built-in role.

[[ml-get-overall-buckets-desc]]
== {api-description-title}

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

By default, an overall bucket has a span equal to the largest bucket span of the
specified {anomaly-jobs}. To override that behavior, use the optional
`bucket_span` parameter. To learn more about the concept of buckets, see
{ml-docs}/ml-buckets.html[Buckets].

The `overall_score` is calculated by combining the scores of all the buckets
within the overall bucket span. First, the maximum `anomaly_score` per
{anomaly-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. If you set
the `bucket_span` parameter (to a value greater than its default), the
`overall_score` is the maximum `overall_score` of the overall buckets that have
a span equal to the jobs' largest bucket span.

[[ml-get-overall-buckets-path-parms]]
== {api-path-parms-title}

`<job_id>`::
(Required, string)
include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=job-id-anomaly-detection-wildcard-list]

[[ml-get-overall-buckets-request-body]]
== {api-request-body-title}

`allow_no_match`::
(Optional, Boolean)
include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=allow-no-jobs]

`bucket_span`::
(Optional, string) The span of the overall buckets. Must be greater or equal to
the largest bucket span of the specified {anomaly-jobs}, which is the default
value.

`end`::
(Optional, string) Returns overall buckets with timestamps earlier than this
time. Defaults to `-1`, which means it is unset and results are not limited to 
specific timestamps.

`exclude_interim`::
(Optional, 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. Defaults to `false`, which means interim results are
included.

`overall_score`::
(Optional, double) Returns overall buckets with overall scores greater or equal
than this value. Defaults to `0.0`.

`start`::
(Optional, string) Returns overall buckets with timestamps after this time. 
Defaults to `-1`, which means it is unset and results are not limited to 
specific timestamps.

`top_n`::
(Optional, integer) The number of top {anomaly-job} bucket scores to be used in
the `overall_score` calculation. Defaults to `1`.

[[ml-get-overall-buckets-results]]
== {api-response-body-title}

The API returns an array of overall bucket objects, which have the following
properties:

`bucket_span`::
(number) The length of the bucket in seconds. Matches the `bucket_span`
of the job with the longest one.

`is_interim`::
(Boolean)
include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=is-interim]

`jobs`::
(array) An array of objects that contain the `max_anomaly_score` per `job_id`.

`overall_score`::
(number) The `top_n` average of the max bucket `anomaly_score` per job.

`result_type`::
(string) Internal. This is always set to `overall_bucket`.

`timestamp`::
(date)
include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=timestamp-results]

[[ml-get-overall-buckets-example]]
== {api-examples-title}

[source,console]
--------------------------------------------------
GET _ml/anomaly_detectors/job-*/results/overall_buckets
{
  "overall_score": 80,
  "start": "1403532000000"
}
--------------------------------------------------
// TEST[skip:todo]

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:
[source,js]
----
{
  "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`:

[source,console]
--------------------------------------------------
GET _ml/anomaly_detectors/job-*/results/overall_buckets
{
  "top_n": 2,
  "overall_score": 50.0,
  "start": "1403532000000"
}
--------------------------------------------------
// TEST[skip:todo]

Note how the `overall_score` is now the average of the top 2 job scores:
[source,js]
----
{
  "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"
    }
  ]
}
----