---
title: Update bandit
description: Update a bandit.
breadcrumbs: Docs > API > Update bandit
---

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

# Update 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 | PATCH https://api.datadoghq.com/api/v2/experiments/bandits/{bandit_id}     |
| us3.datadoghq.com | PATCH https://api.us3.datadoghq.com/api/v2/experiments/bandits/{bandit_id} |
| us5.datadoghq.com | PATCH https://api.us5.datadoghq.com/api/v2/experiments/bandits/{bandit_id} |
| app.datadoghq.eu  | PATCH https://api.datadoghq.eu/api/v2/experiments/bandits/{bandit_id}      |
| ap1.datadoghq.com | PATCH https://api.ap1.datadoghq.com/api/v2/experiments/bandits/{bandit_id} |
| ap2.datadoghq.com | PATCH https://api.ap2.datadoghq.com/api/v2/experiments/bandits/{bandit_id} |
| uk1.datadoghq.com | PATCH https://api.uk1.datadoghq.com/api/v2/experiments/bandits/{bandit_id} |
| app.ddog-gov.com  | PATCH https://api.ddog-gov.com/api/v2/experiments/bandits/{bandit_id}      |
| us2.ddog-gov.com  | PATCH https://api.us2.ddog-gov.com/api/v2/experiments/bandits/{bandit_id}  |

### Overview

Update a bandit. Omitted attributes, including omitted fields of `datadog_flag_configuration` and `bayesian_prior`, are unchanged. `variants`, `tags`, and `teams` replace the stored lists. Setting a nullable attribute to `null` clears it; `datadog_flag_configuration: null` takes a draft off its flag. What can change depends on the status. A draft can change anything. A running or paused bandit can change its name, description, refresh schedule, scheduled end, prior, fallback (send the current arms in `variants` with a different `is_fallback`), tags, and teams. A stopped or completed bandit can change only its tags and teams. Values that don't change can be sent again in any status. Setting `datadog_flag_configuration` or `variants` needs feature flag and environment read permissions and edit access to the flag. Validation can return several field errors at once: HTTP 400 if any is about invalid input, or 409 if all are status conflicts. Bandits must be enabled for the organization.

This endpoint requires the `product_analytics_experiments_write` permission.

OAuth apps require the `product_analytics_experiments_write` 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. |

### Request

#### Body Data (required)

{% tabs %}
{% tab label="Model" %}
| Parent field               | Field                                | Type      | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| -------------------------- | ------------------------------------ | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|                            | data [*required*]                    | object    | Bandit resource with the attributes to change.                                                                                                                                                                                                                                                                                                                                                                                                                                |
| data                       | attributes [*required*]              | object    | The attributes to change. Omitted attributes are unchanged. Which ones can change depends on the bandit's status.                                                                                                                                                                                                                                                                                                                                                             |
| attributes                 | aggregation_window_seconds           | int64     | The aggregation window: how long after an exposure the bandit keeps counting its reward, in seconds. `null` restores the default of 3600 (1 hour). Only a draft can change it.                                                                                                                                                                                                                                                                                                |
| attributes                 | bayesian_prior                       | object    | The prior the bandit's estimates start from, in the metric's units. Omitted fields keep their current values, or their defaults on create. A change takes effect on the next refresh.                                                                                                                                                                                                                                                                                         |
| bayesian_prior             | arm_standard_deviation               | double    | Prior standard deviation of each arm's mean around the shared mean. Must be between 1e-12 and 1e12. Defaults to 100.                                                                                                                                                                                                                                                                                                                                                          |
| bayesian_prior             | grand_mean                           | double    | Prior mean of the shared mean of the arms. Its absolute value must be at most 1e12 times `grand_mean_standard_deviation`. Defaults to 0.                                                                                                                                                                                                                                                                                                                                      |
| bayesian_prior             | grand_mean_standard_deviation        | double    | Prior standard deviation of the shared mean of the arms. Must be between 1e-12 and 1e12, and at most 1e7 times `arm_standard_deviation`. Defaults to 10000.                                                                                                                                                                                                                                                                                                                   |
| attributes                 | datadog_flag_configuration           | object    | The flag and environment the bandit serves on, and who it serves there. The server chooses the rule's `allocation_key`. On create, `feature_flag_id` and `environment_id` are required, and `null` is the same as omitting it. On update, omitted fields are unchanged, and `null` takes a draft off its flag, which also clears its variants and scheduled end. Moving a draft to another flag clears its variants unless the request sets them. Only a draft can change it. |
| datadog_flag_configuration | environment_id                       | uuid      | The environment the bandit serves in.                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| datadog_flag_configuration | feature_flag_id                      | uuid      | The flag the bandit serves through.                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| datadog_flag_configuration | targeting_rules                      | [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                          | string    | The bandit's description.                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| attributes                 | exposure_sql_model_id                | uuid      | The exposure SQL model the bandit reads its exposures from. Only a draft can change it.                                                                                                                                                                                                                                                                                                                                                                                       |
| attributes                 | lookback_seconds                     | int64     | How far back each refresh reads observations, in seconds. `null` restores the default of 2592000 (30 days). Only a draft can change it.                                                                                                                                                                                                                                                                                                                                       |
| attributes                 | metric_id                            | uuid      | The metric the bandit optimizes. It must read a warehouse metric source. Only a draft can change it.                                                                                                                                                                                                                                                                                                                                                                          |
| attributes                 | name                                 | string    | The bandit's name.                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| attributes                 | refresh_schedule_id                  | string    | The schedule the bandit refreshes on.                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| attributes                 | scheduled_end_at                     | date-time | When the bandit ends and serves its fallback. Needs a fallback variant. `null` removes the scheduled end.                                                                                                                                                                                                                                                                                                                                                                     |
| attributes                 | subject_type_id                      | uuid      | The subject type the bandit randomizes and measures by. Only a draft can change it.                                                                                                                                                                                                                                                                                                                                                                                           |
| attributes                 | tags                                 | [string]  | Replaces the bandit's tags and keeps its teams. Allowed in any status.                                                                                                                                                                                                                                                                                                                                                                                                        |
| attributes                 | teams                                | [string]  | Replaces the bandit's teams and keeps its tags. Allowed in any status.                                                                                                                                                                                                                                                                                                                                                                                                        |
| attributes                 | variants                             | [object]  | Replaces the variants the bandit uses. Once the bandit has started, only `is_fallback` can change, so send the current arms with a different `is_fallback`. Only a draft can have an empty list.                                                                                                                                                                                                                                                                              |
| variants                   | feature_flag_variant_id [*required*] | uuid      | The variant's ID on the flag.                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| variants                   | is_active                            | boolean   | Whether the variant is one of the arms the bandit chooses between. Defaults to `true`. Default: `true`.                                                                                                                                                                                                                                                                                                                                                                       |
| variants                   | is_fallback                          | boolean   | Whether the variant is served when the bandit reaches its scheduled end. At most one variant is the fallback, and it doesn't have to be an arm. Defaults to `false`. Default: `false`.                                                                                                                                                                                                                                                                                        |
| attributes                 | warmup_seconds                       | int64     | How long the bandit serves its arms equally after it starts, in seconds. `null` removes the warmup. Only a draft can change it.                                                                                                                                                                                                                                                                                                                                               |
| data                       | id                                   | uuid      | The bandit ID. When present, it must match the path.                                                                                                                                                                                                                                                                                                                                                                                                                          |
| data                       | type [*required*]                    | enum      | Bandit resource type. Allowed enum values: `bandits`. Default: `bandits`.                                                                                                                                                                                                                                                                                                                                                                                                     |
{% /tab %}

{% tab label="Example" %}
```json
{
  "data": {
    "type": "bandits",
    "id": "4b1f3c2e-8d5a-4f6b-9c7e-1a2b3c4d5e6f",
    "attributes": {
      "name": "bandit-14bb9543f523edde-renamed",
      "variants": [
        {
          "feature_flag_variant_id": "550e8400-e29b-41d4-a716-446655440002"
        },
        {
          "feature_flag_variant_id": "8385917b-53d3-23de-914c-c0250ef24884",
          "is_fallback": true
        }
      ]
    }
  }
}
```
{% /tab %}
{% /tabs %}

### 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              | policy_number [*required*]                 | int64     | The policy's place in the bandit's policy history. It follows `applied_at` and orders policies saved at the same time.                                                                                                                                                                              |
| active_policy              | reason [*required*]                        | enum      | Why the policy was applied. Allowed enum values: `ACTIVATION`, `REFRESH`, `ARM_CHANGE`, `SCHEDULED_END`, `STOP`.                                                                                                                                                                                    |
| active_policy              | refresh_id [*required*]                    | uuid      | The refresh that proposed the policy. `null` for policies no refresh proposed, such as the first split and the policy served after the bandit ends.                                                                                                                                                 |
| 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",
        "policy_number": 9,
        "reason": "REFRESH",
        "refresh_id": "bb0e8400-e29b-41d4-a716-446655440000",
        "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, or an invalid request body: a malformed, unknown, read-only, or wrongly `null` attribute, invalid variants or prior, `data.id` not matching the path, or a referenced record that doesn't exist for the organization. May return several errors.

{% 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, the caller lacks the product_analytics_experiments_write permission, or the request changes `datadog_flag_configuration` or `variants` without feature flag and environment read permissions or edit access to the flag and environment.

{% 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="409" %}
The bandit's status doesn't let a requested attribute change (one error per attribute), the bandit moved to another flag during the edit, or a pending change request touches the flag's targeting rules.

{% 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="415" %}
Request body sent with a media type other than application/json or application/vnd.api+json.

{% 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 PATCH "https://api.${DD_SITE}/api/v2/experiments/bandits/${bandit_id}" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${DD_BEARER_TOKEN}" \
-d @- << EOF
{
  "data": {
    "type": "bandits",
    "id": "4b1f3c2e-8d5a-4f6b-9c7e-1a2b3c4d5e6f",
    "attributes": {
      "name": "bandit-14bb9543f523edde-renamed",
      "variants": [
        {
          "feature_flag_variant_id": "550e8400-e29b-41d4-a716-446655440002"
        },
        {
          "feature_flag_variant_id": "8385917b-53d3-23de-914c-c0250ef24884",
          "is_fallback": true
        }
      ]
    }
  }
}
EOF
```
{% /tab %}
{% /tabs %}
