Experiments

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.

patch/api/v2/experiments/bandits/{bandit_id}

Request

  • Base URL
    https://api.datadoghq.com
  • Auth
    • API key in header DD-API-KEY and API key in header DD-APPLICATION-KEY
    • or OAuth 2
      Authorization code/oauth2/v1/authorize
      Token URL/oauth2/v1/token
      Scopesproduct_analytics_experiments_write

Path parameters

bandit_idstring uuid required

The UUID of the bandit.

Example:4b1f3c2e-8d5a-4f6b-9c7e-1a2b3c4d5e6f

Request body

Example request

{
  "data": {
    "attributes": {
      "aggregation_window_seconds": 3600,
      "bayesian_prior": {
        "arm_standard_deviation": 100,
        "grand_mean_standard_deviation": 10000
      },
      "datadog_flag_configuration": {
        "environment_id": "660e8400-e29b-41d4-a716-446655440000",
        "feature_flag_id": "550e8400-e29b-41d4-a716-446655440000",
        "targeting_rules": []
      },
      "description": "Find the button color that maximizes checkout revenue.",
      "exposure_sql_model_id": "aa0e8400-e29b-41d4-a716-446655440000",
      "lookback_seconds": 2592000,
      "metric_id": "990e8400-e29b-41d4-a716-446655440000",
      "name": "Checkout button color",
      "refresh_schedule_id": "cc0e8400-e29b-41d4-a716-446655440000",
      "scheduled_end_at": "2026-12-08T00:00:00Z",
      "subject_type_id": "880e8400-e29b-41d4-a716-446655440000",
      "tags": [
        "checkout"
      ],
      "teams": [
        "growth"
      ],
      "variants": [
        {
          "feature_flag_variant_id": "770e8400-e29b-41d4-a716-446655440001",
          "is_active": true,
          "is_fallback": true
        }
      ],
      "warmup_seconds": 86400
    },
    "id": "4b1f3c2e-8d5a-4f6b-9c7e-1a2b3c4d5e6f",
    "type": "bandits"
  }
}

Response

OK

Example response

{
  "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_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": []
      },
      "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."
      }
    ]
  }
}

Changes

    • warning

      the optional response header X-RateLimit-Limit removed for the status 429

    • warning

      the optional response header X-RateLimit-Period removed for the status 429

    • warning

      the optional response header X-RateLimit-Remaining removed for the status 429

    1 more change in this revision