---
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/4641/api/doc/elasticsearch/v8/operation/operation-ml-get-buckets
resource: https://www.elastic.co/elastic/docs-builder/docs/4641/api/doc/elasticsearch/v8/operation/operation-ml-get-buckets
products:
  - Elasticsearch
---

# Get anomaly detection job results for buckets

Authentication: required

Availability: Generally available since 5.4

## Paths

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

#### Path parameters

- `job_id` (string) — required
  Identifier for the anomaly detection job.
- `timestamp` (union oneOf) — 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 `number`

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

## 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` (union oneOf · default: -1) — optional
  Refer to the description for the `end` query parameter.
  One of: `string` or `number`
- `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` (object) — 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 · default: timestamp) — optional
  Refer to the desription for the `sort` query parameter.
- `start` (union oneOf · default: -1) — optional
  Refer to the description for the `start` query parameter.
  One of: `string` or `number`

## Response

`application/json`

- `buckets` (object[])
  - `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` (object[])
    - `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` (number)
      The length of the bucket in seconds. This value matches the bucket span that is specified in the job.
    - `influencer_field_name` (string)
      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)
      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` (number)
      The start time of the bucket for which these results were calculated.
    - `timestamp_string` (union oneOf)
      The start time of the bucket for which these results were calculated.
      One of: `string` or `number`
  - `bucket_span` (number)
    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)
    Identifier for the anomaly detection job.
  - `processing_time_ms` (number)
    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` (number)
    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` (union oneOf)
    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.
    One of: `string` or `number`
- `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"
  }
)
```

## Response examples

#### 200

`application/json`

Generated from the API spec. Values are representative. Unions use the first variant; deeply nested or large bodies may omit fields.

```json
{
  "buckets": [
    {
      "anomaly_score": 0,
      "bucket_influencers": [
        {
          "anomaly_score": 0,
          "influencer_field_name": "string",
          "initial_anomaly_score": 0,
          "is_interim": false,
          "job_id": "string",
          "probability": 0,
          "raw_anomaly_score": 0,
          "result_type": "string"
        }
      ],
      "bucket_span": 0,
      "event_count": 0,
      "initial_anomaly_score": 0,
      "is_interim": false,
      "job_id": "string",
      "processing_time_ms": 0,
      "result_type": "string",
      "timestamp": 0,
      "timestamp_string": "string"
    }
  ],
  "count": 0
}
```