---
type: api
title: Get anomaly detection job results for buckets
description: **All methods and paths for this operation:**
url: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/elasticsearch/v9/operation/operation-ml-get-buckets
resource: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/elasticsearch/v9/operation/operation-ml-get-buckets
products:
  - Elasticsearch
---

# Get anomaly detection job results for buckets


Availability: 5.4+

## Paths

- `POST` (also `GET`) `/_ml/anomaly_detectors/{job_id}/results/buckets/{timestamp}`
- `POST` (also `GET`) `/_ml/anomaly_detectors/{job_id}/results/buckets`

- [Api key auth](/elastic/docs-builder/docs/4371/api/doc/elasticsearch/v9/authentication#apikeyauth)
- [Basic auth](/elastic/docs-builder/docs/4371/api/doc/elasticsearch/v9/authentication#basicauth)
- [Bearer auth](/elastic/docs-builder/docs/4371/api/doc/elasticsearch/v9/authentication#bearerauth)

#### Path Parameters

- `job_id` (string Id)
  Identifier for the anomaly detection job.
- `timestamp` (union DateTime) — optional, leave it out to use `/_ml/anomaly_detectors/{job_id}/results/buckets`
  The timestamp of a single bucket result. If you do not specify this
parameter, the API returns information about all buckets.
  One of: `string` or `EpochTimeUnitMillis`

## Description

The API presents a chronological view of the records, grouped by bucket.

## Required authorization

* Cluster privileges: `monitor_ml`

## Query String Parameters

- `anomaly_score` (number · default: 0)
  Returns buckets with anomaly scores greater or equal than this value.
- `desc` (boolean · default: false)
  If `true`, the buckets are sorted in descending order.
- `end` (DateTime · default: -1)
  Returns buckets with timestamps earlier than this time. `-1` means it is
unset and results are not limited to specific timestamps.
- `exclude_interim` (boolean · default: false)
  If `true`, the output excludes interim results.
- `expand` (boolean · default: false)
  If true, the output includes anomaly records.
- `from` (number · default: 0)
  Skips the specified number of buckets.
- `size` (number · default: 100)
  Specifies the maximum number of buckets to obtain.
- `sort` (string Field · default: timestamp)
  Specifies the sort field for the requested buckets.
- `start` (DateTime · default: -1)
  Returns buckets with timestamps after this time. `-1` means it is unset
and results are not limited to specific timestamps.

## Request Body

`application/json`

- `anomaly_score` (number · default: 0) — optional
  Refer to the description for the `anomaly_score` query parameter.
- `desc` (boolean · default: false) — optional
  Refer to the description for the `desc` query parameter.
- `end` (DateTime · default: -1) — optional
  Refer to the description for the `end` query parameter.
- `exclude_interim` (boolean · default: false) — optional
  Refer to the description for the `exclude_interim` query parameter.
- `expand` (boolean · default: false) — optional
  Refer to the description for the `expand` query parameter.
- `page` ({} Page) — optional
  - `from` (number · default: 0) — optional
    Skips the specified number of items.
  - `size` (number · default: 10000) — optional
    Specifies the maximum number of items to obtain.
- `sort` (string Field · default: timestamp) — optional
  Refer to the desription for the `sort` query parameter.
- `start` (DateTime · default: -1) — optional
  Refer to the description for the `start` query parameter.

## Response

`application/json`

- `buckets` ([] BucketSummary)
  - `anomaly_score` (number)
    The maximum anomaly score, between 0-100, for any of the bucket influencers. This is an overall, rate-limited
score for the job. All the anomaly records in the bucket contribute to this score. This value might be updated as
new data is analyzed.
  - `bucket_influencers` ([] BucketInfluencer)
    - `anomaly_score` (number)
      A normalized score between 0-100, which is calculated for each bucket influencer. This score might be updated as
newer data is analyzed.
    - `bucket_span` (DurationValueUnitSeconds)
      The length of the bucket in seconds. This value matches the bucket span that is specified in the job.
    - `influencer_field_name` (string Field)
      The field name of the influencer.
    - `initial_anomaly_score` (number)
      The score between 0-100 for each bucket influencer. This score is the initial value that was calculated at the
time the bucket was processed.
    - `is_interim` (boolean)
      If true, this is an interim result. In other words, the results are calculated based on partial input data.
    - `job_id` (string Id)
      Identifier for the anomaly detection job.
    - `probability` (number)
      The probability that the bucket has this behavior, in the range 0 to 1. This value can be held to a high precision
of over 300 decimal places, so the `anomaly_score` is provided as a human-readable and friendly interpretation of
this.
    - `raw_anomaly_score` (number)
      Internal.
    - `result_type` (string)
      Internal. This value is always set to `bucket_influencer`.
    - `timestamp` (EpochTimeUnitMillis)
      The start time of the bucket for which these results were calculated.
    - `timestamp_string` (DateTime)
      The start time of the bucket for which these results were calculated.
  - `bucket_span` (DurationValueUnitSeconds)
    The length of the bucket in seconds. This value matches the bucket span that is specified in the job.
  - `event_count` (number)
    The number of input data records processed in this bucket.
  - `initial_anomaly_score` (number)
    The maximum anomaly score for any of the bucket influencers. This is the initial value that was calculated at the
time the bucket was processed.
  - `is_interim` (boolean)
    If true, this is an interim result. In other words, the results are calculated based on partial input data.
  - `job_id` (string Id)
    Identifier for the anomaly detection job.
  - `processing_time_ms` (DurationValueUnitMillis)
    The amount of time, in milliseconds, that it took to analyze the bucket contents and calculate results.
  - `result_type` (string)
    Internal. This value is always set to bucket.
  - `timestamp` (EpochTimeUnitMillis)
    The start time of the bucket. This timestamp uniquely identifies the bucket. Events that occur exactly at the
timestamp of the bucket are included in the results for the bucket.
  - `timestamp_string` (DateTime)
    The start time of the bucket. This timestamp uniquely identifies the bucket. Events that occur exactly at the
timestamp of the bucket are included in the results for the bucket.
- `count` (number)
## Code Examples

#### Console

```console
POST _ml/anomaly_detectors/low_request_rate/results/buckets
{
  "anomaly_score": 80,
  "start": "1454530200001"
}
```

#### JavaScript

```javascript
const response = await client.ml.getBuckets({
  job_id: "low_request_rate",
  anomaly_score: 80,
  start: 1454530200001,
});
```

#### Python

```python
resp = client.ml.get_buckets(
    job_id="low_request_rate",
    anomaly_score=80,
    start="1454530200001",
)
```

#### curl

```curl
curl -X POST "$ELASTICSEARCH_URL/_ml/anomaly_detectors/low_request_rate/results/buckets" \
  -H "Authorization: ApiKey $ELASTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "anomaly_score": 80,
    "start": "1454530200001"
  }'
```

#### Java

```java
client.ml().getBuckets(g -> g
    .anomalyScore(80.0D)
    .jobId("low_request_rate")
    .start(DateTime.of("1454530200001"))
);
```

#### C#

```c#
var response = await client.MachineLearning
    .GetBucketsAsync(new GetBucketsRequest()
    {
        JobId = "low_request_rate",
        AnomalyScore = 80d,
        Start = DateTimeOffset.Parse("2016-02-03T20:10:00.0010000+00:00", CultureInfo.InvariantCulture, DateTimeStyles.RoundtripKind)
    });
```

#### PHP

```php
$resp = $client->ml()->getBuckets([
    "job_id" => "low_request_rate",
    "body" => [
        "anomaly_score" => 80,
        "start" => "1454530200001",
    ],
]);
```

#### Ruby

```ruby
response = client.ml.get_buckets(
  job_id: "low_request_rate",
  body: {
    "anomaly_score": 80,
    "start": "1454530200001"
  }
)
```