---
title: "Update bandit"
method: PATCH
path: "/api/v2/experiments/bandits/{bandit_id}"
tags: ["Experiments"]
---

# Update bandit

`PATCH /api/v2/experiments/bandits/{bandit_id}`

## Request

- Base URL: `https://api.datadoghq.com`
- URL: `https://api.datadoghq.com/api/v2/experiments/bandits/{bandit_id}`
- Auth: one of:
  - API key in header `DD-API-KEY` and API key in header `DD-APPLICATION-KEY`
  - OAuth 2
    - Authorization code: `/oauth2/v1/authorize`
    - Token URL: `/oauth2/v1/token` scopes: `product_analytics_experiments_write`

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.

## Path parameters

- `bandit_id` string, uuid, required: The UUID of the bandit.

## Request body

- ExperimentsPatchBanditV2Request: Request to update a bandit.
  - `data` ExperimentsPatchBanditV2RequestData, required: Bandit resource with the attributes to change.
    - `attributes` ExperimentsPatchBanditV2RequestDataAttributes, required: The attributes to change. Omitted attributes are unchanged. Which ones can change depends on the bandit's status.
      - `aggregation_window_seconds` integer, nullable: 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.
      - `bayesian_prior` ExperimentsBanditBayesianPriorInputV2: 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.
        - `arm_standard_deviation` number, double: Prior standard deviation of each arm's mean around the shared mean. Must be between 1e-12 and 1e12. Defaults to 100.
        - `grand_mean` number, 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.
        - `grand_mean_standard_deviation` number, 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.
      - `datadog_flag_configuration` ExperimentsBanditFlagConfigurationInputV2, nullable: 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.
        - `environment_id` string, uuid: The environment the bandit serves in.
        - `feature_flag_id` string, uuid: The flag the bandit serves through.
        - `targeting_rules` ExperimentsTargetingRule[]: Who the bandit serves. When empty, the bandit serves everyone in the environment.
          - `conditions` ExperimentsTargetingRuleCondition[], required: 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.
            - union: A saved-filter condition or a complete inline condition. The two forms cannot be combined.
              - …
      - `description` string: The bandit's description.
      - `exposure_sql_model_id` string, uuid, nullable: The exposure SQL model the bandit reads its exposures from. Only a draft can change it.
      - `lookback_seconds` integer, nullable: How far back each refresh reads observations, in seconds. `null` restores the default of 2592000 (30 days). Only a draft can change it.
      - `metric_id` string, uuid, nullable: The metric the bandit optimizes. It must read a warehouse metric source. Only a draft can change it.
      - `name` string: The bandit's name.
      - `refresh_schedule_id` string: The schedule the bandit refreshes on.
      - `scheduled_end_at` string, date-time, nullable: When the bandit ends and serves its fallback. Needs a fallback variant. `null` removes the scheduled end.
      - `subject_type_id` string, uuid, nullable: The subject type the bandit randomizes and measures by. Only a draft can change it.
      - `tags` string[]: Replaces the bandit's tags and keeps its teams. Allowed in any status.
      - `teams` string[]: Replaces the bandit's teams and keeps its tags. Allowed in any status.
      - `variants` ExperimentsBanditVariantInputV2[]: 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.
        - `feature_flag_variant_id` string, uuid, required: The variant's ID on the flag.
        - `is_active` boolean: Whether the variant is one of the arms the bandit chooses between. Defaults to `true`.
        - `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`.
      - `warmup_seconds` integer, nullable: How long the bandit serves its arms equally after it starts, in seconds. `null` removes the warmup. Only a draft can change it.
    - `id` string, uuid: The bandit ID. When present, it must match the path.
    - `type` 'bandits', required: Bandit resource type.

## Response `200`

OK

- ExperimentsBanditV2DTO: Response containing a bandit.
  - `data` ExperimentsBanditV2DTOData, required: JSON:API resource containing a bandit.
    - `attributes` ExperimentsBanditV2DTODataAttributes, required: A bandit's setup, the policy it serves, and its latest refresh.
      - `active_policy` ExperimentsBanditPolicyV2, nullable, required: The policy the bandit serves. `null` until the bandit starts.
        - `applied_at` string, date-time, required: When the policy started being served.
        - `config_version` integer, required: The configuration version the policy was made for.
        - `id` string, uuid, required: The policy ID. Each exposure logs it as `bandit.policy_id`.
        - `kind` 'WARMUP' | 'ADAPTIVE' | 'FALLBACK', required: `WARMUP` serves the arms equally. `ADAPTIVE` serves the initial split or a split from a refresh. `FALLBACK` serves one variant after the bandit ends.
        - `policy_number` integer, required: The policy's place in the bandit's policy history. It follows `applied_at` and orders policies saved at the same time.
        - `reason` 'ACTIVATION' | 'REFRESH' | 'ARM_CHANGE' | 'SCHEDULED_END' | 'STOP', required: Why the policy was applied.
        - `refresh_id` string, uuid, nullable, required: 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.
        - `variants` ExperimentsBanditPolicyVariantV2[], required: Each variant's share of traffic. The probabilities add up to 1.
          - `feature_flag_variant_id` string, uuid, required: The variant's ID on the flag.
          - `probability` number, double, required: The share of traffic the variant gets, from 0 to 1.
          - `variant_key` string, nullable, required: The variant's key. `null` when it can't be resolved.
      - `aggregation_window_seconds` integer, required: The aggregation window: how long after an exposure the bandit keeps counting its reward, in seconds.
      - `bayesian_prior` ExperimentsBanditBayesianPriorV2, required: The prior the bandit's estimates start from.
        - `arm_standard_deviation` number, double, required: Prior standard deviation of each arm's mean around the shared mean.
        - `grand_mean` number, double, required: Prior mean of the shared mean of the arms, in the metric's units.
        - `grand_mean_standard_deviation` number, double, required: Prior standard deviation of the shared mean of the arms.
      - `config_version` integer, required: The version of the bandit's configuration. Each saved change adds one.
      - `created_at` string, date-time, required: When the bandit was created.
      - `datadog_flag_configuration` ExperimentsBanditFlagConfigurationV2: 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`.
        - `allocation_key` string, required: The key of the bandit's rule on the flag. Exposures log it.
        - `environment_id` string, uuid, required: The environment the bandit serves in.
        - `feature_flag_id` string, uuid, required: The flag the bandit serves through.
        - `targeting_rules` ExperimentsTargetingRule[], required: Who the bandit serves. When empty, the bandit serves everyone in the environment.
          - `conditions` ExperimentsTargetingRuleCondition[], required: 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.
            - union: A saved-filter condition or a complete inline condition. The two forms cannot be combined.
              - …
      - `description` string, required: The bandit's description.
      - `ended_at` string, date-time, nullable, required: When the bandit was stopped or reached its scheduled end. `null` while it hasn't ended.
      - `exposure_sql_model_id` string, uuid, nullable, required: The exposure SQL model the bandit reads its exposures from. `null` until set on a draft.
      - `latest_refresh` ExperimentsBanditRefreshV2, nullable, required: The most recently started refresh. `null` until one starts.
        - `created_at` string, date-time, required: When the refresh was requested.
        - `ended_at` string, date-time, nullable, required: When the refresh finished. `null` while it runs.
        - `id` string, uuid, required: The refresh ID.
        - `started_at` string, date-time, nullable, required: When the refresh started running. `null` while it is pending.
        - `status` 'PENDING' | 'RUNNING' | 'SUCCEEDED' | 'FAILED' | 'CANCELLED', required: The status of the refresh.
      - `lookback_seconds` integer, required: How far back each refresh reads observations, in seconds.
      - `metric_id` string, uuid, nullable, required: The metric the bandit optimizes. `null` until set on a draft.
      - `name` string, required: The bandit's name.
      - `optimal_variant_key` string, nullable, required: 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.
      - `optimal_variant_unavailable_reason` 'NO_RESULTS_YET' | 'WARMUP' | 'NOT_ENOUGH_DATA' | 'NO_DIFFERENCE' | 'STATS_UNAVAILABLE': Why no optimal variant is reported. Absent when one is, or when the cause isn't known.
      - `refresh_schedule_id` string, nullable, required: The schedule the bandit refreshes on.
      - `scheduled_end_at` string, date-time, nullable, required: When the bandit ends and serves its fallback. `null` when it has no scheduled end.
      - `scheduled_end_failure` ExperimentsBanditScheduledEndFailureV2: Why the scheduled end couldn't run. It isn't retried until the end date or fallback changes. Absent when there's no failure.
        - `failed_at` string, date-time, required: When the scheduled end failed.
        - `reason` string, required: Why the scheduled end failed.
      - `started_at` string, date-time, nullable, required: When the bandit started. `null` until it starts.
      - `status` 'DRAFT' | 'SCHEDULED' | 'RUNNING' | 'PAUSED' | 'STOPPED' | 'COMPLETED', required: 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.
      - `subject_type_id` string, uuid, nullable, required: The subject type the bandit randomizes and measures by. `null` until set on a draft.
      - `tags` string[], required: The bandit's tags, without team tags.
      - `teams` string[], required: Handles of the teams that own the bandit.
      - `updated_at` string, date-time, required: When the bandit was last changed.
      - `variants` ExperimentsBanditVariantV2[], required: The flag variants the bandit uses: its arms in arm order, then its fallback when the fallback isn't an arm.
        - `feature_flag_variant_id` string, uuid, required: The variant's ID on the flag.
        - `is_active` boolean, required: Whether the variant is one of the arms the bandit chooses between.
        - `is_fallback` boolean, required: Whether the variant is served when the bandit reaches its scheduled end. At most one variant is the fallback.
        - `key` string, nullable, required: 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.
        - `name` string, nullable, required: The variant's name on the flag. `null` when it is no longer on the flag.
      - `warmup_seconds` integer, nullable, required: How long the bandit serves its arms equally after it starts, in seconds. `null` when it has no warmup.
    - `id` string, uuid, required: The bandit ID.
    - `type` 'bandits', required: Bandit resource type.
  - `meta` ExperimentsBanditV2ReadMetaDTO: Information about the bandit response.
    - `warnings` ExperimentsBanditV2WarningDTO[]: Warnings about the response. Absent when there are none.
      - `code` 'datadog_flag_configuration_omitted', required: 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`.
      - `detail` string, required: Explanation of the warning.

## Other responses

- `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.
- `401`: Missing or invalid authentication (dd-api-key + dd-application-key headers, or a valid user session).
- `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.
- `404`: No bandit with this ID exists for the organization.
- `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.
- `415`: Request body sent with a media type other than application/json or application/vnd.api+json.
- `429`: Too many requests

## Changes

- **2026-11-20** `3b1c63e31740`: 4 warning
  - the optional response header `X-RateLimit-Limit` removed for the status `429`
  - the optional response header `X-RateLimit-Period` removed for the status `429`
  - the optional response header `X-RateLimit-Remaining` removed for the status `429`
  - the optional response header `X-RateLimit-Reset` removed for the status `429`
- **2026-11-19** `8623cd014a4f`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/datadog/apis/datadog-api-v2-collection/changes/api/v2/experiments/bandits/:bandit_id/patch.md)

---

[API](https://skmtc.dev/datadog/apis/datadog-api-v2-collection.md) - [All operations](https://skmtc.dev/datadog/apis/datadog-api-v2-collection/llms.txt) - [OpenAPI document](https://skmtc.dev/datadog/apis/datadog-api-v2-collection/revisions/4ba32926196d?raw)
