Patch experiment

PATCH https://api.ap1.datadoghq.com/api/v2/experiments/{experiment_id}https://api.ap2.datadoghq.com/api/v2/experiments/{experiment_id}https://api.datadoghq.eu/api/v2/experiments/{experiment_id}https://api.ddog-gov.com/api/v2/experiments/{experiment_id}https://api.us2.ddog-gov.com/api/v2/experiments/{experiment_id}https://api.uk1.datadoghq.com/api/v2/experiments/{experiment_id}https://api.datadoghq.com/api/v2/experiments/{experiment_id}https://api.us3.datadoghq.com/api/v2/experiments/{experiment_id}https://api.us5.datadoghq.com/api/v2/experiments/{experiment_id}

Overview

Update mutable experiment fields. State and protocol restrictions apply.

PATCH behavior

• Omitted fields stay unchanged, including fields inside datadog_flag_configuration.
• Supplied tags, teams, related_links, decision_metrics, and variants replace their stored lists.
• Validation can return several field errors before saving any changes. The response is HTTP 400 if any error concerns invalid input. It is HTTP 409 if all errors concern state or protocol conflicts.

Result refreshes

This endpoint does not start a pipeline run. meta.needs_pipeline_refresh states whether the edit requires a run. When true, POST to meta.refresh_endpoint after finishing your edits. Its full_refresh query parameter selects the run type.

Keep refresh requirements across edits. A later false value does not clear an earlier requirement. Any full_refresh=true requirement takes priority.

After start, STATIC and STEPS exposure changes for warehouse experiments without a Datadog flag attempt to recalculate stored results. Changes to decision metrics or the control variant also attempt recalculation when results exist. If stored data is insufficient or recalculation fails, the edit stays saved and meta.needs_pipeline_refresh is true.

Exposure rules

• Draft experiments can replace the full STATIC or STEPS plan through traffic_exposure.
• Warehouse steps start at assignments_start_date and can have different durations.
• Running warehouse experiments can replace step fractions, durations, and exposure mode. Retained variant weights cannot change through this API. You can send unchanged values again.
• After a warehouse experiment ends, configuration replacement supports only STATIC fraction changes.
• New Datadog plans have at most five steps. The first fraction must be positive. All steps except the last have equal durations. Durations exclude pauses.
• The last step has a null duration. Its fraction stays in effect until assignment ends.
• After start, use the experiment UI to change traffic exposure for experiments linked to a Datadog flag.

Metadata

structured_metadata updates fields by field_key. Use freetext_value: "" or enum_values: [] to clear an optional field. Omitted fields stay unchanged. A null or empty structured_metadata attribute makes no change.

Flag changes

Before start, a Datadog update creates or edits the saved draft allocation. To add or replace a flag, send variants and traffic_exposure. Inside datadog_flag_configuration, send feature_flag_id, environment_id, targeting_rules, and entry_point. Use targeting_rules: [] and entry_point: null when unused.

To replace a flag, also set reset_on_feature_flag_change: true inside that object. The server deletes the old draft and creates a new one in the same transaction. The response includes a datadog_flag_configuration_reset warning in meta.warnings.

Set datadog_flag_configuration: null to delete the draft allocation. This also clears the experiment’s flag association, variants, assignment sources, and entry point. The experiment remains.

Flag replacement and removal require a draft experiment without warehouse exposure. These actions do not convert hybrid experiments.

OAuth apps require the product_analytics_experiments_write authorization scope to access this endpoint.

Arguments

Path Parameters

Request

Body Data (required)

{
  "data": {
    "type": "experiments",
    "attributes": {
      "name": "ex-14bb9543f523edde updated"
    }
  }
}

Response

• 200
• 400
• 401
• 403
• 404
• 409
• 415
• 429

{
  "data": {
    "attributes": {
      "assignments_end_date": "2026-08-15T00:00:00Z",
      "assignments_start_date": "2026-08-01T00:00:00Z",
      "concluded_at": "2026-08-05T09:30:00Z",
      "conclusion": {
        "decision_reason": "The primary metric improved without material regressions",
        "outcome": "POSITIVE",
        "summary": "The treatment improved conversion"
      },
      "created_at": "2026-08-01T12:00:00Z",
      "datadog_flag_configuration": null,
      "decision_metrics": [
        {
          "is_primary": true,
          "metric_id": "b1a2c3d4-0000-0000-0000-000000000000"
        }
      ],
      "decision_variant_key": "treatment",
      "events_end_date": "2026-08-22T00:00:00Z",
      "events_start_date": "2026-08-01T00:00:00Z",
      "experiment_type": "STANDARD",
      "hypothesis": "A clearer checkout button increases purchase conversion",
      "name": "Checkout button test",
      "pipeline_table_suffix": "a1b2c3d4",
      "protocol_id": "e4d5f6a7-0000-0000-0000-000000000000",
      "related_links": [
        {
          "id": "d1d2d3d4-0000-0000-0000-000000000000",
          "title": "Experiment design",
          "url": "https://docs.example.com/checkout-experiment"
        }
      ],
      "results_last_updated": "2026-08-05T09:25:00Z",
      "split_by_properties": [],
      "status": "DECISION_MADE",
      "structured_metadata": [
        {
          "enum_values": [
            "beta"
          ],
          "field_display_name": "Launch stage",
          "field_key": "launch_stage",
          "field_type": "ENUM"
        },
        {
          "field_display_name": "Notes",
          "field_key": "notes",
          "field_type": "FREETEXT",
          "freetext_value": "Checkout redesign"
        }
      ],
      "subject_type_id": "c2b3d4e5-0000-0000-0000-000000000000",
      "summary": "The treatment improved conversion",
      "tags": [
        "growth"
      ],
      "teams": [
        "growth"
      ],
      "traffic_exposure": {
        "fraction": 1,
        "mode": "STATIC"
      },
      "updated_at": "2026-08-05T09:30:00Z",
      "variants": [
        {
          "is_active": true,
          "is_control": true,
          "key": "control",
          "name": "Control",
          "weight": 50
        },
        {
          "is_active": true,
          "is_control": false,
          "key": "treatment",
          "name": "Treatment",
          "weight": 50
        }
      ],
      "warehouse_exposure_configuration": {
        "entry_point": null,
        "experiment_key": "checkout_button_test",
        "exposure_sql_model_id": "f5e6a7b8-0000-0000-0000-000000000000"
      }
    },
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "type": "experiments"
  }
}

{
  "errors": [
    {
      "detail": "Missing required attribute in body",
      "meta": {},
      "source": {
        "header": "Authorization",
        "parameter": "limit",
        "pointer": "/data/attributes/title"
      },
      "status": "400",
      "title": "Bad Request"
    }
  ]
}

{
  "errors": [
    {
      "detail": "Missing required attribute in body",
      "meta": {},
      "source": {
        "header": "Authorization",
        "parameter": "limit",
        "pointer": "/data/attributes/title"
      },
      "status": "400",
      "title": "Bad Request"
    }
  ]
}

{
  "errors": [
    {
      "detail": "Missing required attribute in body",
      "meta": {},
      "source": {
        "header": "Authorization",
        "parameter": "limit",
        "pointer": "/data/attributes/title"
      },
      "status": "400",
      "title": "Bad Request"
    }
  ]
}

{
  "errors": [
    {
      "detail": "Missing required attribute in body",
      "meta": {},
      "source": {
        "header": "Authorization",
        "parameter": "limit",
        "pointer": "/data/attributes/title"
      },
      "status": "400",
      "title": "Bad Request"
    }
  ]
}

{
  "errors": [
    {
      "detail": "Missing required attribute in body",
      "meta": {},
      "source": {
        "header": "Authorization",
        "parameter": "limit",
        "pointer": "/data/attributes/title"
      },
      "status": "400",
      "title": "Bad Request"
    }
  ]
}

{
  "errors": [
    {
      "detail": "Missing required attribute in body",
      "meta": {},
      "source": {
        "header": "Authorization",
        "parameter": "limit",
        "pointer": "/data/attributes/title"
      },
      "status": "400",
      "title": "Bad Request"
    }
  ]
}

{
  "errors": [
    "Bad Request"
  ]
}

Code Example

                          ## default
# 

# Path parameters
export experiment_id="550e8400-e29b-41d4-a716-446655440000"
# Use a Personal Access Token or Service Access Token
export DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>"

# Curl command
curl -X PATCH "https://api.ap1.datadoghq.com"https://api.ap2.datadoghq.com"https://api.datadoghq.eu"https://api.ddog-gov.com"https://api.us2.ddog-gov.com"https://api.uk1.datadoghq.com"https://api.datadoghq.com"https://api.us3.datadoghq.com"https://api.us5.datadoghq.com/api/v2/experiments/${experiment_id}" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${DD_BEARER_TOKEN}" \
-d @- << EOF
{
  "data": {
    "attributes": {
      "datadog_flag_configuration": {
        "entry_point": null,
        "environment_id": "550e8400-e29b-41d4-a716-446655440005",
        "feature_flag_id": "550e8400-e29b-41d4-a716-446655440014",
        "reset_on_feature_flag_change": true,
        "targeting_rules": []
      },
      "structured_metadata": [
        {
          "enum_values": [
            "general_availability"
          ],
          "field_key": "launch_stage"
        }
      ],
      "traffic_exposure": {
        "fraction": 1,
        "mode": "STATIC"
      },
      "variants": [
        {
          "feature_flag_variant_id": "550e8400-e29b-41d4-a716-446655440020",
          "is_active": true,
          "is_control": true,
          "key": "control",
          "weight": 50
        },
        {
          "feature_flag_variant_id": "550e8400-e29b-41d4-a716-446655440021",
          "is_active": true,
          "is_control": false,
          "key": "treatment",
          "weight": 50
        }
      ]
    },
    "type": "experiments"
  }
}
EOF