---
title: Create bandit
description: Create a draft bandit. name is required; you can set everything else now, or later with PATCH /api/v2/experiments/bandits/{bandit_id}.
breadcrumbs: Docs > API > Create bandit
---

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

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

### Overview

Create a draft bandit. `name` is required; you can set everything else now, or later with PATCH `/api/v2/experiments/bandits/{bandit_id}`. A draft on a flag holds a targeting rule that doesn't serve traffic until the bandit starts. `variants` lists the flag variants the bandit uses by `feature_flag_variant_id`: `is_active` makes a variant an arm (the default), and `is_fallback` marks the variant served after a scheduled end. The server fills in each variant's `key` and `name` from the flag. A scheduled end needs a fallback. Setting `datadog_flag_configuration` or `variants` needs feature flag and environment read permissions and edit access to the flag. Whether the draft is ready to run is checked when it starts. Validation can return several field errors at once. This endpoint is not idempotent. 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.

### Request

#### Body Data (required)

{% tabs %}
{% tab label="Model" %}
| Parent field               | Field                                | Type      | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| -------------------------- | ------------------------------------ | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|                            | data [*required*]                    | object    | Bandit resource to create.                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| data                       | attributes [*required*]              | object    | The new draft's setup. Only `name` is required. Whether the draft is ready to run is checked when it starts.                                                                                                                                                                                                                                                                                                                                                                  |
| attributes                 | aggregation_window_seconds           | int64     | The aggregation window: how long after an exposure the bandit keeps counting its reward, in seconds. Defaults to 3600 (1 hour).                                                                                                                                                                                                                                                                                                                                               |
| 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. Defaults to empty.                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| attributes                 | exposure_sql_model_id                | uuid      | The exposure SQL model the bandit reads its exposures from.                                                                                                                                                                                                                                                                                                                                                                                                                   |
| attributes                 | lookback_seconds                     | int64     | How far back each refresh reads observations, in seconds. Defaults to 2592000 (30 days).                                                                                                                                                                                                                                                                                                                                                                                      |
| attributes                 | metric_id                            | uuid      | The metric the bandit optimizes. It must read a warehouse metric source.                                                                                                                                                                                                                                                                                                                                                                                                      |
| attributes                 | name [*required*]                    | string    | The bandit's name.                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| attributes                 | refresh_schedule_id                  | string    | The schedule the bandit refreshes on. Defaults to the organization's default schedule.                                                                                                                                                                                                                                                                                                                                                                                        |
| attributes                 | scheduled_end_at                     | date-time | When the bandit ends and serves its fallback. Needs a fallback variant.                                                                                                                                                                                                                                                                                                                                                                                                       |
| attributes                 | subject_type_id                      | uuid      | The subject type the bandit randomizes and measures by.                                                                                                                                                                                                                                                                                                                                                                                                                       |
| attributes                 | tags                                 | [string]  | Tags for the bandit. The flag's tags are added too.                                                                                                                                                                                                                                                                                                                                                                                                                           |
| attributes                 | teams                                | [string]  | Handles of the teams that own the bandit.                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| attributes                 | variants                             | [object]  | The flag variants the bandit uses. Needs `datadog_flag_configuration`. The server fills in each variant's `key` and `name` from the flag.                                                                                                                                                                                                                                                                                                                                     |
| 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. Defaults to no warmup.                                                                                                                                                                                                                                                                                                                                                                               |
| data                       | type [*required*]                    | enum      | Bandit resource type. Allowed enum values: `bandits`. Default: `bandits`.                                                                                                                                                                                                                                                                                                                                                                                                     |
{% /tab %}

{% tab label="Example" %}
```json
{
  "data": {
    "type": "bandits",
    "attributes": {
      "name": "bandit-14bb9543f523edde",
      "datadog_flag_configuration": {
        "feature_flag_id": "550e8400-e29b-41d4-a716-446655440000",
        "environment_id": "550e8400-e29b-41d4-a716-446655440001",
        "targeting_rules": []
      },
      "variants": [
        {
          "feature_flag_variant_id": "550e8400-e29b-41d4-a716-446655440002",
          "is_fallback": true
        },
        {
          "feature_flag_variant_id": "8385917b-53d3-23de-914c-c0250ef24884"
        }
      ],
      "subject_type_id": "550e8400-e29b-41d4-a716-446655440010",
      "tags": [
        "bdd"
      ]
    }
  }
}
```
{% /tab %}
{% /tabs %}

### Response

{% tabs %}
{% tab label="201" %}
Created

{% 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" %}
Invalid request body: a missing name, a malformed or unknown attribute, a read-only attribute, invalid variants or prior, or a referenced flag, variant, environment, metric, subject type, exposure SQL model, or schedule 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 sets `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="409" %}
The request conflicts with the flag's current state; for example, a pending change request touches its 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
# 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 POST "https://api.${DD_SITE}/api/v2/experiments/bandits" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${DD_BEARER_TOKEN}" \
-d @- << EOF
{
  "data": {
    "type": "bandits",
    "attributes": {
      "name": "bandit-14bb9543f523edde",
      "datadog_flag_configuration": {
        "feature_flag_id": "550e8400-e29b-41d4-a716-446655440000",
        "environment_id": "550e8400-e29b-41d4-a716-446655440001",
        "targeting_rules": []
      },
      "variants": [
        {
          "feature_flag_variant_id": "550e8400-e29b-41d4-a716-446655440002",
          "is_fallback": true
        },
        {
          "feature_flag_variant_id": "8385917b-53d3-23de-914c-c0250ef24884"
        }
      ],
      "subject_type_id": "550e8400-e29b-41d4-a716-446655440010",
      "tags": [
        "bdd"
      ]
    }
  }
}
EOF
```
{% /tab %}
{% /tabs %}
