---
title: Get bandit
description: "Get a bandit: its setup, the policy it serves, its latest refresh, and the arm most likely to be best."
breadcrumbs: Docs > API > Get bandit
---

> For the complete documentation index, see [llms.txt](https://docs.datadoghq.com/llms.txt).

# Get bandit

{% callout %}
This product or feature is not supported for the following sites: app.ddog-gov.com, us2.ddog-gov.com
{% /callout %}

## v2 (latest)

{% alert level="warning" %}
**Note**: This endpoint is in preview and is subject to change.
If you have any feedback, contact [Datadog support](https://docs.datadoghq.com/help.md).
{% /alert %}

| Datadog site      | API endpoint                                                             |
| ----------------- | ------------------------------------------------------------------------ |
| app.datadoghq.com | GET https://api.datadoghq.com/api/v2/experiments/bandits/{bandit_id}     |
| us3.datadoghq.com | GET https://api.us3.datadoghq.com/api/v2/experiments/bandits/{bandit_id} |
| us5.datadoghq.com | GET https://api.us5.datadoghq.com/api/v2/experiments/bandits/{bandit_id} |
| app.datadoghq.eu  | GET https://api.datadoghq.eu/api/v2/experiments/bandits/{bandit_id}      |
| ap1.datadoghq.com | GET https://api.ap1.datadoghq.com/api/v2/experiments/bandits/{bandit_id} |
| ap2.datadoghq.com | GET https://api.ap2.datadoghq.com/api/v2/experiments/bandits/{bandit_id} |
| uk1.datadoghq.com | GET https://api.uk1.datadoghq.com/api/v2/experiments/bandits/{bandit_id} |
| app.ddog-gov.com  | GET https://api.ddog-gov.com/api/v2/experiments/bandits/{bandit_id}      |
| us2.ddog-gov.com  | GET https://api.us2.ddog-gov.com/api/v2/experiments/bandits/{bandit_id}  |

### Overview

Get a bandit: its setup, the policy it serves, its latest refresh, and the arm most likely to be best. When the caller lacks feature flag or environment read permissions, the response omits `datadog_flag_configuration` and `meta.warnings` includes `datadog_flag_configuration_omitted`. Bandits must be enabled for the organization.

This endpoint requires the `product_analytics_experiments_read` permission.

OAuth apps require the `product_analytics_experiments_read` authorization [scope](https://docs.datadoghq.com/api/latest/scopes.md#experiments) to access this endpoint.

### Arguments

#### Path Parameters

| Field                  | Type   | Description             |
| ---------------------- | ------ | ----------------------- |
| bandit_id [*required*] | string | The UUID of the bandit. |

### Response

{% tabs %}
{% tab label="200" %}
OK

{% tabs %}
{% tab label="Model" %}
Response containing a bandit.

| Parent field               | Field                                      | Type      | Description                                                                                                                                                                                                                                                                                         |
| -------------------------- | ------------------------------------------ | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|                            | data [*required*]                          | object    | JSON:API resource containing a bandit.                                                                                                                                                                                                                                                              |
| data                       | attributes [*required*]                    | object    | A bandit's setup, the policy it serves, and its latest refresh.                                                                                                                                                                                                                                     |
| attributes                 | active_policy [*required*]                 | object    | The policy the bandit serves. `null` until the bandit starts.                                                                                                                                                                                                                                       |
| active_policy              | applied_at [*required*]                    | date-time | When the policy started being served.                                                                                                                                                                                                                                                               |
| active_policy              | config_version [*required*]                | int64     | The configuration version the policy was made for.                                                                                                                                                                                                                                                  |
| active_policy              | id [*required*]                            | uuid      | The policy ID. Each exposure logs it as `bandit.policy_id`.                                                                                                                                                                                                                                         |
| active_policy              | kind [*required*]                          | enum      | `WARMUP` serves the arms equally. `ADAPTIVE` serves the initial split or a split from a refresh. `FALLBACK` serves one variant after the bandit ends. Allowed enum values: `WARMUP`, `ADAPTIVE`, `FALLBACK`.                                                                                        |
| active_policy              | reason [*required*]                        | enum      | Why the policy was applied. Allowed enum values: `ACTIVATION`, `REFRESH`, `ARM_CHANGE`, `SCHEDULED_END`, `STOP`.                                                                                                                                                                                    |
| active_policy              | variants [*required*]                      | [object]  | Each variant's share of traffic. The probabilities add up to 1.                                                                                                                                                                                                                                     |
| variants                   | feature_flag_variant_id [*required*]       | uuid      | The variant's ID on the flag.                                                                                                                                                                                                                                                                       |
| variants                   | probability [*required*]                   | double    | The share of traffic the variant gets, from 0 to 1.                                                                                                                                                                                                                                                 |
| variants                   | variant_key [*required*]                   | string    | The variant's key. `null` when it can't be resolved.                                                                                                                                                                                                                                                |
| attributes                 | aggregation_window_seconds [*required*]    | int64     | The aggregation window: how long after an exposure the bandit keeps counting its reward, in seconds.                                                                                                                                                                                                |
| attributes                 | bayesian_prior [*required*]                | object    | The prior the bandit's estimates start from.                                                                                                                                                                                                                                                        |
| bayesian_prior             | arm_standard_deviation [*required*]        | double    | Prior standard deviation of each arm's mean around the shared mean.                                                                                                                                                                                                                                 |
| bayesian_prior             | grand_mean [*required*]                    | double    | Prior mean of the shared mean of the arms, in the metric's units.                                                                                                                                                                                                                                   |
| bayesian_prior             | grand_mean_standard_deviation [*required*] | double    | Prior standard deviation of the shared mean of the arms.                                                                                                                                                                                                                                            |
| attributes                 | config_version [*required*]                | int64     | The version of the bandit's configuration. Each saved change adds one.                                                                                                                                                                                                                              |
| attributes                 | created_at [*required*]                    | date-time | When the bandit was created.                                                                                                                                                                                                                                                                        |
| attributes                 | datadog_flag_configuration                 | object    | The flag rule the bandit serves through. Absent until a draft is added to a flag. Also absent when the caller lacks feature flag or environment read permissions, in which case `meta.warnings` includes `datadog_flag_configuration_omitted`.                                                      |
| datadog_flag_configuration | allocation_key [*required*]                | string    | The key of the bandit's rule on the flag. Exposures log it.                                                                                                                                                                                                                                         |
| datadog_flag_configuration | environment_id [*required*]                | uuid      | The environment the bandit serves in.                                                                                                                                                                                                                                                               |
| datadog_flag_configuration | feature_flag_id [*required*]               | uuid      | The flag the bandit serves through.                                                                                                                                                                                                                                                                 |
| datadog_flag_configuration | targeting_rules [*required*]               | [object]  | Who the bandit serves. When empty, the bandit serves everyone in the environment.                                                                                                                                                                                                                   |
| targeting_rules            | conditions [*required*]                    | [<oneOf>] | Conditions that must all match for this rule. Each condition must use exactly one shape: saved_filter_id alone or operator plus attribute plus value.                                                                                                                                               |
| conditions                 | Object 1                                   | object    | A condition that uses a saved filter. Inline fields must be omitted or null.                                                                                                                                                                                                                        |
| Object 1                   | saved_filter_id [*required*]               | uuid      | Saved-filter UUID.                                                                                                                                                                                                                                                                                  |
| conditions                 | Object 2                                   | object    | An inline condition. The saved_filter_id field must be omitted or null.                                                                                                                                                                                                                             |
| Object 2                   | attribute [*required*]                     | string    | Attribute to evaluate.                                                                                                                                                                                                                                                                              |
| Object 2                   | operator [*required*]                      | enum      | Required with attribute and value for an inline condition; omit when saved_filter_id is set. Allowed enum values: `LT`, `LTE`, `GT`, `GTE`, `MATCHES`, `NOT_MATCHES`, `ONE_OF`, `NOT_ONE_OF`, `IS_NULL`, `EQUALS`, `SEMVER_EQ`, `SEMVER_NEQ`, `SEMVER_LT`, `SEMVER_LTE`, `SEMVER_GT`, `SEMVER_GTE`. |
| Object 2                   | value [*required*]                         | [string]  | Values used by the operator. Every operator requires at least one value.                                                                                                                                                                                                                            |
| attributes                 | description [*required*]                   | string    | The bandit's description.                                                                                                                                                                                                                                                                           |
| attributes                 | ended_at [*required*]                      | date-time | When the bandit was stopped or reached its scheduled end. `null` while it hasn't ended.                                                                                                                                                                                                             |
| attributes                 | exposure_sql_model_id [*required*]         | uuid      | The exposure SQL model the bandit reads its exposures from. `null` until set on a draft.                                                                                                                                                                                                            |
| attributes                 | latest_refresh [*required*]                | object    | The most recently started refresh. `null` until one starts.                                                                                                                                                                                                                                         |
| latest_refresh             | created_at [*required*]                    | date-time | When the refresh was requested.                                                                                                                                                                                                                                                                     |
| latest_refresh             | ended_at [*required*]                      | date-time | When the refresh finished. `null` while it runs.                                                                                                                                                                                                                                                    |
| latest_refresh             | id [*required*]                            | uuid      | The refresh ID.                                                                                                                                                                                                                                                                                     |
| latest_refresh             | started_at [*required*]                    | date-time | When the refresh started running. `null` while it is pending.                                                                                                                                                                                                                                       |
| latest_refresh             | status [*required*]                        | enum      | The status of the refresh. Allowed enum values: `PENDING`, `RUNNING`, `SUCCEEDED`, `FAILED`, `CANCELLED`.                                                                                                                                                                                           |
| attributes                 | lookback_seconds [*required*]              | int64     | How far back each refresh reads observations, in seconds.                                                                                                                                                                                                                                           |
| attributes                 | metric_id [*required*]                     | uuid      | The metric the bandit optimizes. `null` until set on a draft.                                                                                                                                                                                                                                       |
| attributes                 | name [*required*]                          | string    | The bandit's name.                                                                                                                                                                                                                                                                                  |
| attributes                 | optimal_variant_key [*required*]           | string    | The key of the arm most likely to be best, when one arm leads and the bandit is outside warmup. `null` otherwise. Matches Get bandit results.                                                                                                                                                       |
| attributes                 | optimal_variant_unavailable_reason         | enum      | Why no optimal variant is reported. Absent when one is, or when the cause isn't known. Allowed enum values: `NO_RESULTS_YET`, `WARMUP`, `NOT_ENOUGH_DATA`, `NO_DIFFERENCE`, `STATS_UNAVAILABLE`.                                                                                                    |
| attributes                 | refresh_schedule_id [*required*]           | string    | The schedule the bandit refreshes on.                                                                                                                                                                                                                                                               |
| attributes                 | scheduled_end_at [*required*]              | date-time | When the bandit ends and serves its fallback. `null` when it has no scheduled end.                                                                                                                                                                                                                  |
| attributes                 | scheduled_end_failure                      | object    | Why the scheduled end couldn't run. It isn't retried until the end date or fallback changes. Absent when there's no failure.                                                                                                                                                                        |
| scheduled_end_failure      | failed_at [*required*]                     | date-time | When the scheduled end failed.                                                                                                                                                                                                                                                                      |
| scheduled_end_failure      | reason [*required*]                        | string    | Why the scheduled end failed.                                                                                                                                                                                                                                                                       |
| attributes                 | started_at [*required*]                    | date-time | When the bandit started. `null` until it starts.                                                                                                                                                                                                                                                    |
| attributes                 | status [*required*]                        | enum      | The bandit's status. `STOPPED` means the bandit was stopped and serves the variant chosen then. `COMPLETED` means it reached its scheduled end and serves its fallback. Allowed enum values: `DRAFT`, `SCHEDULED`, `RUNNING`, `PAUSED`, `STOPPED`, `COMPLETED`.                                     |
| attributes                 | subject_type_id [*required*]               | uuid      | The subject type the bandit randomizes and measures by. `null` until set on a draft.                                                                                                                                                                                                                |
| attributes                 | tags [*required*]                          | [string]  | The bandit's tags, without team tags.                                                                                                                                                                                                                                                               |
| attributes                 | teams [*required*]                         | [string]  | Handles of the teams that own the bandit.                                                                                                                                                                                                                                                           |
| attributes                 | updated_at [*required*]                    | date-time | When the bandit was last changed.                                                                                                                                                                                                                                                                   |
| attributes                 | variants [*required*]                      | [object]  | The flag variants the bandit uses: its arms in arm order, then its fallback when the fallback isn't an arm.                                                                                                                                                                                         |
| variants                   | feature_flag_variant_id [*required*]       | uuid      | The variant's ID on the flag.                                                                                                                                                                                                                                                                       |
| variants                   | is_active [*required*]                     | boolean   | Whether the variant is one of the arms the bandit chooses between.                                                                                                                                                                                                                                  |
| variants                   | is_fallback [*required*]                   | boolean   | Whether the variant is served when the bandit reaches its scheduled end. At most one variant is the fallback.                                                                                                                                                                                       |
| variants                   | key [*required*]                           | string    | The variant's key. An arm keeps the key it had when it was added, because exposures are matched on it. `null` only for a fallback deleted from the flag.                                                                                                                                            |
| variants                   | name [*required*]                          | string    | The variant's name on the flag. `null` when it is no longer on the flag.                                                                                                                                                                                                                            |
| attributes                 | warmup_seconds [*required*]                | int64     | How long the bandit serves its arms equally after it starts, in seconds. `null` when it has no warmup.                                                                                                                                                                                              |
| data                       | id [*required*]                            | uuid      | The bandit ID.                                                                                                                                                                                                                                                                                      |
| data                       | type [*required*]                          | enum      | Bandit resource type. Allowed enum values: `bandits`. Default: `bandits`.                                                                                                                                                                                                                           |
|                            | meta                                       | object    | Information about the bandit response.                                                                                                                                                                                                                                                              |
| meta                       | warnings                                   | [object]  | Warnings about the response. Absent when there are none.                                                                                                                                                                                                                                            |
| warnings                   | code [*required*]                          | enum      | Code that identifies the warning. `datadog_flag_configuration_omitted` means the caller lacks feature flag or environment read permissions, so the response leaves out `datadog_flag_configuration`. Allowed enum values: `datadog_flag_configuration_omitted`.                                     |
| warnings                   | detail [*required*]                        | string    | Explanation of the warning.                                                                                                                                                                                                                                                                         |
{% /tab %}

{% tab label="Example" %}
```json
{
  "data": {
    "attributes": {
      "active_policy": {
        "applied_at": "2026-10-30T02:15:00Z",
        "config_version": 2,
        "id": "dd0e8400-e29b-41d4-a716-446655440000",
        "kind": "ADAPTIVE",
        "reason": "REFRESH",
        "variants": [
          {
            "feature_flag_variant_id": "770e8400-e29b-41d4-a716-446655440001",
            "probability": 0.3,
            "variant_key": "blue"
          }
        ]
      },
      "aggregation_window_seconds": 3600,
      "bayesian_prior": {
        "arm_standard_deviation": 100,
        "grand_mean": 0,
        "grand_mean_standard_deviation": 10000
      },
      "config_version": 2,
      "created_at": "2026-10-22T12:00:00Z",
      "datadog_flag_configuration": {
        "allocation_key": "checkout-button-color-bandit",
        "environment_id": "660e8400-e29b-41d4-a716-446655440000",
        "feature_flag_id": "550e8400-e29b-41d4-a716-446655440000",
        "targeting_rules": [
          {
            "conditions": [
              []
            ]
          }
        ]
      },
      "description": "Find the button color that maximizes checkout revenue.",
      "ended_at": "2026-12-01T00:00:00Z",
      "exposure_sql_model_id": "aa0e8400-e29b-41d4-a716-446655440000",
      "latest_refresh": {
        "created_at": "2026-10-30T00:00:00Z",
        "ended_at": "2026-10-30T02:15:00Z",
        "id": "bb0e8400-e29b-41d4-a716-446655440000",
        "started_at": "2026-10-30T00:02:00Z",
        "status": "SUCCEEDED"
      },
      "lookback_seconds": 2592000,
      "metric_id": "990e8400-e29b-41d4-a716-446655440000",
      "name": "Checkout button color",
      "optimal_variant_key": "green",
      "optimal_variant_unavailable_reason": "NOT_ENOUGH_DATA",
      "refresh_schedule_id": "cc0e8400-e29b-41d4-a716-446655440000",
      "scheduled_end_at": "2026-12-01T00:00:00Z",
      "scheduled_end_failure": {
        "failed_at": "2026-12-01T00:00:05Z",
        "reason": "The fallback variant is no longer on the flag."
      },
      "started_at": "2026-10-23T09:00:00Z",
      "status": "RUNNING",
      "subject_type_id": "880e8400-e29b-41d4-a716-446655440000",
      "tags": [
        "checkout"
      ],
      "teams": [
        "growth"
      ],
      "updated_at": "2026-10-30T02:15:00Z",
      "variants": [
        {
          "feature_flag_variant_id": "770e8400-e29b-41d4-a716-446655440001",
          "is_active": true,
          "is_fallback": true,
          "key": "blue",
          "name": "Blue"
        }
      ],
      "warmup_seconds": 86400
    },
    "id": "4b1f3c2e-8d5a-4f6b-9c7e-1a2b3c4d5e6f",
    "type": "bandits"
  },
  "meta": {
    "warnings": [
      {
        "code": "datadog_flag_configuration_omitted",
        "detail": "The Datadog flag configuration is not included because feature flag and environment read permissions are required to view it. The bandit still has its flag configuration."
      }
    ]
  }
}
```
{% /tab %}
{% /tabs %}
{% /tab %}

{% tab label="400" %}
Malformed bandit ID (not a valid UUID).

{% tabs %}
{% tab label="Model" %}
API error response.

| Parent field | Field               | Type     | Description                                                                     |
| ------------ | ------------------- | -------- | ------------------------------------------------------------------------------- |
|              | errors [*required*] | [object] | A list of errors.                                                               |
| errors       | code                | string   | An application-specific error code.                                             |
| errors       | detail              | string   | A human-readable explanation specific to this occurrence of the error.          |
| errors       | meta                | object   | Non-standard meta-information about the error                                   |
| errors       | source              | object   | References to the source of the error.                                          |
| source       | header              | string   | A string indicating the name of a single request header which caused the error. |
| source       | parameter           | string   | A string indicating which URI query parameter caused the error.                 |
| source       | pointer             | string   | A JSON pointer to the value in the request document that caused the error.      |
| errors       | status              | string   | Status code of the response.                                                    |
| errors       | title               | string   | Short human-readable summary of the error.                                      |
{% /tab %}

{% tab label="Example" %}
```json
{
  "errors": [
    {
      "code": "invalid_request",
      "detail": "Missing required attribute in body",
      "meta": {},
      "source": {
        "header": "Authorization",
        "parameter": "limit",
        "pointer": "/data/attributes/title"
      },
      "status": "400",
      "title": "Bad Request"
    }
  ]
}
```
{% /tab %}
{% /tabs %}
{% /tab %}

{% tab label="401" %}
Missing or invalid authentication (dd-api-key + dd-application-key headers, or a valid user session).

{% tabs %}
{% tab label="Model" %}
API error response.

| Parent field | Field               | Type     | Description                                                                     |
| ------------ | ------------------- | -------- | ------------------------------------------------------------------------------- |
|              | errors [*required*] | [object] | A list of errors.                                                               |
| errors       | code                | string   | An application-specific error code.                                             |
| errors       | detail              | string   | A human-readable explanation specific to this occurrence of the error.          |
| errors       | meta                | object   | Non-standard meta-information about the error                                   |
| errors       | source              | object   | References to the source of the error.                                          |
| source       | header              | string   | A string indicating the name of a single request header which caused the error. |
| source       | parameter           | string   | A string indicating which URI query parameter caused the error.                 |
| source       | pointer             | string   | A JSON pointer to the value in the request document that caused the error.      |
| errors       | status              | string   | Status code of the response.                                                    |
| errors       | title               | string   | Short human-readable summary of the error.                                      |
{% /tab %}

{% tab label="Example" %}
```json
{
  "errors": [
    {
      "code": "invalid_request",
      "detail": "Missing required attribute in body",
      "meta": {},
      "source": {
        "header": "Authorization",
        "parameter": "limit",
        "pointer": "/data/attributes/title"
      },
      "status": "400",
      "title": "Bad Request"
    }
  ]
}
```
{% /tab %}
{% /tabs %}
{% /tab %}

{% tab label="403" %}
Bandits are not enabled for the organization, or the caller lacks the product_analytics_experiments_read permission.

{% tabs %}
{% tab label="Model" %}
API error response.

| Parent field | Field               | Type     | Description                                                                     |
| ------------ | ------------------- | -------- | ------------------------------------------------------------------------------- |
|              | errors [*required*] | [object] | A list of errors.                                                               |
| errors       | code                | string   | An application-specific error code.                                             |
| errors       | detail              | string   | A human-readable explanation specific to this occurrence of the error.          |
| errors       | meta                | object   | Non-standard meta-information about the error                                   |
| errors       | source              | object   | References to the source of the error.                                          |
| source       | header              | string   | A string indicating the name of a single request header which caused the error. |
| source       | parameter           | string   | A string indicating which URI query parameter caused the error.                 |
| source       | pointer             | string   | A JSON pointer to the value in the request document that caused the error.      |
| errors       | status              | string   | Status code of the response.                                                    |
| errors       | title               | string   | Short human-readable summary of the error.                                      |
{% /tab %}

{% tab label="Example" %}
```json
{
  "errors": [
    {
      "code": "invalid_request",
      "detail": "Missing required attribute in body",
      "meta": {},
      "source": {
        "header": "Authorization",
        "parameter": "limit",
        "pointer": "/data/attributes/title"
      },
      "status": "400",
      "title": "Bad Request"
    }
  ]
}
```
{% /tab %}
{% /tabs %}
{% /tab %}

{% tab label="404" %}
No bandit with this ID exists for the organization.

{% tabs %}
{% tab label="Model" %}
API error response.

| Parent field | Field               | Type     | Description                                                                     |
| ------------ | ------------------- | -------- | ------------------------------------------------------------------------------- |
|              | errors [*required*] | [object] | A list of errors.                                                               |
| errors       | code                | string   | An application-specific error code.                                             |
| errors       | detail              | string   | A human-readable explanation specific to this occurrence of the error.          |
| errors       | meta                | object   | Non-standard meta-information about the error                                   |
| errors       | source              | object   | References to the source of the error.                                          |
| source       | header              | string   | A string indicating the name of a single request header which caused the error. |
| source       | parameter           | string   | A string indicating which URI query parameter caused the error.                 |
| source       | pointer             | string   | A JSON pointer to the value in the request document that caused the error.      |
| errors       | status              | string   | Status code of the response.                                                    |
| errors       | title               | string   | Short human-readable summary of the error.                                      |
{% /tab %}

{% tab label="Example" %}
```json
{
  "errors": [
    {
      "code": "invalid_request",
      "detail": "Missing required attribute in body",
      "meta": {},
      "source": {
        "header": "Authorization",
        "parameter": "limit",
        "pointer": "/data/attributes/title"
      },
      "status": "400",
      "title": "Bad Request"
    }
  ]
}
```
{% /tab %}
{% /tabs %}
{% /tab %}

{% tab label="429" %}
Too many requests

{% tabs %}
{% tab label="Model" %}
API error response.

| Field               | Type     | Description       |
| ------------------- | -------- | ----------------- |
| errors [*required*] | [string] | A list of errors. |
{% /tab %}

{% tab label="Example" %}
```json
{
  "errors": [
    "Bad Request"
  ]
}
```
{% /tab %}
{% /tabs %}
{% /tab %}
{% /tabs %}

### Code Example

{% tabs %}
{% tab label="Curl" %}
```bash
# Path parameters
export bandit_id="4b1f3c2e-8d5a-4f6b-9c7e-1a2b3c4d5e6f"

# Set your Datadog site and credentials
export DD_SITE="datadoghq.com" # Or us3.datadoghq.com, us5.datadoghq.com, datadoghq.eu, ap1.datadoghq.com, ap2.datadoghq.com, uk1.datadoghq.com, ddog-gov.com, us2.ddog-gov.com
# Use a Personal Access Token or Service Access Token
export DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>"

curl -X GET "https://api.${DD_SITE}/api/v2/experiments/bandits/${bandit_id}" \
-H "Accept: application/json" \
-H "Authorization: Bearer ${DD_BEARER_TOKEN}"
```
{% /tab %}
{% /tabs %}
