Experiments

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.

post/api/v2/experiments/bandits

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

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-01T00: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
    },
    "type": "bandits"
  }
}

Response

Created

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