OpenSearch/docs/java-rest/high-level/ml/get-overall-buckets.asciidoc

--
:api: get-overall-buckets
:request: GetOverallBucketsRequest
:response: GetOverallBucketsResponse
--
[id="{upid}-{api}"]
=== Get overall buckets API

Retrieves overall bucket results that summarize the bucket results of multiple
{anomaly-jobs}.
It accepts a +{request}+ object and responds
with a +{response}+ object.

[id="{upid}-{api}-request"]
==== Get overall buckets request

A +{request}+ object gets created with one or more `jobId`.

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests-file}[{api}-request]
--------------------------------------------------
<1> Constructing a new request referencing job IDs `jobId1` and `jobId2`.

==== Optional arguments
The following arguments are optional:

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests-file}[{api}-bucket-span]
--------------------------------------------------
<1> The span of the overall buckets. Must be greater or equal to the jobs'
largest `bucket_span`.

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests-file}[{api}-end]
--------------------------------------------------
<1> Overall buckets with timestamps earlier than this time will be returned.

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests-file}[{api}-exclude-interim]
--------------------------------------------------
<1> If `true`, interim results will be excluded. Overall buckets are interim if
any of the job buckets within the overall bucket interval are interim. Defaults
to `false`.

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests-file}[{api}-overall-score]
--------------------------------------------------
<1> Overall buckets with overall scores greater or equal than this value will be
returned.

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests-file}[{api}-start]
--------------------------------------------------
<1> Overall buckets with timestamps on or after this time will be returned.

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests-file}[{api}-top-n]
--------------------------------------------------
<1> The number of top job bucket scores to be used in the `overall_score`
calculation. Defaults to `1`.

include::../execution.asciidoc[]

[id="{upid}-{api}-response"]
==== Get overall buckets response

The returned +{response}+ contains the requested buckets:

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests-file}[{api}-response]
--------------------------------------------------
<1> The count of overall buckets that were matched.
<2> The overall buckets retrieved.