---
title: "Patch experiment"
method: PATCH
path: "/api/v2/experiments/{experiment_id}"
tags: ["Experiments"]
---

# Patch experiment

`PATCH /api/v2/experiments/{experiment_id}`

## Request

- Base URL: `https://api.datadoghq.com`
- URL: `https://api.datadoghq.com/api/v2/experiments/{experiment_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`
- TypeScript: <https://skmtc.dev/datadog/apis/datadog-api-v2-collection/docs/api/v2/experiments/:experiment_id/patch.ts> (a function with typed inputs; its response is checked against the schema)

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.

## Path parameters

- `experiment_id` string, uuid, required: The UUID of the experiment.

## Request body

- ExperimentsPatchExperimentV2Request: Request to update the experiment.
  - `data` ExperimentsPatchExperimentV2RequestData, required: JSON:API resource containing the experiment identity and fields.
    - `attributes` ExperimentsPatchExperimentV2RequestDataAttributes: Fields supplied to update the experiment.
      - `assignments_end_date` string, date-time, nullable: End of the time window for experiment assignments.
      - `assignments_start_date` string, date-time, nullable: Start of the time window for experiment assignments.
      - `datadog_flag_configuration` ExperimentsPatchExperimentV2RequestDataAttributesDatadogFlagConfiguration, nullable: Feature flag, environment, and targeting configuration for the experiment.
        - `entry_point` ExperimentsPatchExperimentV2ResponseDataAttributesDatadogFlagConfigurationEntryPoint, nullable: Datadog measure and filters used to select analyzed subjects.
          - `filters` ExperimentsDatadogEntryPointFilterGroup[], required: Complete Datadog OR-of-ANDs entry-point filter expression.
            - ExperimentsDatadogEntryPointFilter[]: Entry-point filters combined with AND.
              - …
          - `measure_id` string, required: Datadog measure UUID.
        - `environment_id` string: ID of the feature flag environment used by the experiment.
        - `feature_flag_id` string: ID of the feature flag linked to the experiment.
        - `reset_on_feature_flag_change` boolean: Set true to replace an existing draft allocation when feature_flag_id changes. The replacement resets all flag-bound randomization state.
        - `targeting_rules` ExperimentsTargetingRule[]: Omit to keep the stored rules. Use an empty array to remove targeting rules.
          - `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.
              - …
      - `decision_metrics` ExperimentsCreateExperimentV2RequestDataAttributesDecisionMetricsItems[]: Metrics used to decide the experiment outcome.
        - `is_primary` boolean, required: Whether this is the experiment primary metric.
        - `metric_id` string, uuid, required: Decision metric UUID.
      - `events_end_date` string, date-time, nullable: End of the time window for metric events.
      - `events_start_date` string, date-time, nullable: Start of the time window for metric events.
      - `hypothesis` string: Expected effect that the experiment is intended to test.
      - `migration_metadata` unknown
      - `name` string: Display name of the experiment.
      - `related_links` ExperimentsCreateExperimentV2RequestDataAttributesRelatedLinksItems[]: Links to supporting material for the experiment.
        - `id` string, nullable: Link ID. Omit it when adding a link.
        - `title` string, nullable: Optional display title.
        - `url` string, required: Absolute URL.
      - `split_by_properties` ExperimentsCreateExperimentV2RequestDataAttributesSplitByPropertiesItems[]: Complete replacement for the Datadog split-by selection. Identify each property by column_name. Omit this field to leave the selection unchanged.
        - `column_name` string, required: Exposure field that identifies the property.
        - `column_type` 'varchar' | 'int' | 'double' | 'boolean' | 'varchar_array' | 'int_array' | 'double_array' | 'raw': Data type of the column evaluated by the entry-point filter.
        - `name` string: Optional display name. Defaults to column_name for a new property.
      - `structured_metadata` ExperimentsCreateExperimentV2RequestDataAttributesStructuredMetadataItems[], nullable: Metadata values to update. Omit this field, send null, or send an empty array to leave metadata unchanged.
        - `enum_values` string[]: Selected values for an enumerated metadata field.
        - `field_key` string, required: Key that identifies the metadata field.
        - `freetext_value` string: Text value for a free-text metadata field.
      - `subject_type_id` string: ID of the subject type used by this configuration.
      - `summary` string, nullable: Summary text recorded for the experiment.
      - `tags` string[]: Tags attached to the experiment.
      - `teams` string[]: Teams associated with the experiment.
      - `traffic_exposure` ExperimentsPatchExperimentV2ResponseDataAttributesTrafficExposure: Traffic exposure fraction or schedule configured for the experiment.
        - `fraction` number, double: STATIC exposure fraction. Draft experiments can change this value. After start only warehouse experiments without a Datadog flag can change a STATIC fraction through the public API.
        - `mode` 'STATIC' | 'STEPS', required: Whether exposure uses a fixed fraction or a sequence of steps.
        - `steps` ExperimentsCreateExperimentV2RequestDataAttributesTrafficExposureStepsItems[]: Configured exposure plan rather than wall-clock history. At least two steps must have strictly increasing fractions and no gaps. Warehouse steps start at assignments_start_date and can use different durations. New Datadog plans have at most five steps and a first fraction above zero. Their nonfinal durations must be equal and exclude time paused. Datadog steps start with the experiment. Running warehouse experiments can replace step fractions, durations, and the exposure mode. After start, Datadog exposure plans cannot change through the public API. The final duration is null and its fraction holds until assignment ends.
          - `duration_ms` integer, nullable, required: Positive step duration in milliseconds. Datadog durations exclude pauses. Send null for the final step.
          - `fraction` number, double, required: Fraction of traffic exposed during this step.
      - `variants` ExperimentsCreateExperimentV2RequestDataAttributesVariantsItems[]: Variants configured for the experiment.
        - `feature_flag_variant_id` string, uuid: Stable backing flag variant ID. Required for Datadog-backed experiments and omitted for Warehouse-only experiments.
        - `is_active` boolean: Whether this variant participates in the experiment. Responses always include this field. On writes an included variant defaults to active; omit its row to remove or unselect it. Explicit false supports sending an unchanged response back.
        - `is_control` boolean, required: Whether this is the single control variant.
        - `key` string, required: Assignment value. Datadog flag variant keys are server-owned.
        - `name` string, nullable: Display name. Datadog flag variant names are server-owned.
        - `weight` number, double, required: Traffic allocation percentage. Existing variant weights cannot change through the public API after the experiment starts.
      - `warehouse_exposure_configuration` ExperimentsCreateExperimentV2RequestDataAttributesWarehouseExposureConfiguration, nullable: Warehouse model and experiment key used to read assignment data.
        - `entry_point` ExperimentsWarehouseEntryPoint, nullable, required: Optional Warehouse measure that scopes analyzed subjects.
          - `filters` ExperimentsWarehouseExposureFilter[], required: Complete ordered Warehouse entry-point filter set.
            - `operation` 'IS' | 'IS_NOT', required: Comparison applied by the warehouse entry-point filter.
            - `property_id` string, required: Warehouse property UUID.
            - `values` string[], required: Ordered values used by the filter.
          - `measure_id` string, required: Warehouse measure UUID.
        - `experiment_key` string, required: Warehouse experiment key. Must not be blank.
        - `exposure_sql_model_id` string, required: ID of the exposure SQL model that provides assignment data.
    - `id` string: ID of the experiment.
    - `type` 'experiments', required: Experiments resource type.

## Response `200`

OK

- ExperimentsPatchExperimentV2Response: Response containing the updated experiment, refresh requirements, and warnings.
  - `data` ExperimentsExperimentV2DTOData, required: Experiment resource with its identifier and configuration.
    - `attributes` ExperimentsPatchExperimentV2ResponseDataAttributes: Details of the experiment.
      - `assignments_end_date` string, date-time, nullable: End of the time window for experiment assignments.
      - `assignments_start_date` string, date-time, nullable: Start of the time window for experiment assignments.
      - `concluded_at` string, date-time, nullable: Time when the experiment was concluded.
      - `conclusion` ExperimentsPatchExperimentV2ResponseDataAttributesConclusion: Outcome and supporting text recorded when the experiment is concluded.
        - `decision_reason` string, nullable: Reason for the recorded decision.
        - `outcome` 'POSITIVE' | 'NEGATIVE' | 'NEUTRAL' | 'INCONCLUSIVE' | 'MISCONFIGURED' | 'UNKNOWN', nullable: Recorded experiment outcome.
        - `summary` string, nullable: Summary of the experiment conclusion.
      - `created_at` string, date-time: Time when this resource was created.
      - `datadog_flag_configuration` ExperimentsPatchExperimentV2ResponseDataAttributesDatadogFlagConfiguration, nullable: Feature flag, environment, and targeting configuration for the experiment.
        - `allocation_key` string: Key of the feature flag allocation linked to the experiment. Matches the allocation key that SDKs report in flag evaluation results and exposure events.
        - `entry_point` ExperimentsPatchExperimentV2ResponseDataAttributesDatadogFlagConfigurationEntryPoint, nullable, required: Datadog measure and filters used to select analyzed subjects.
          - `filters` ExperimentsDatadogEntryPointFilterGroup[], required: Complete Datadog OR-of-ANDs entry-point filter expression.
            - ExperimentsDatadogEntryPointFilter[]: Entry-point filters combined with AND.
              - …
          - `measure_id` string, required: Datadog measure UUID.
        - `environment_id` string: ID of the feature flag environment used by the experiment.
        - `feature_flag_id` string: ID of the feature flag linked to the experiment.
        - `targeting_rules` ExperimentsTargetingRule[]: Rules that select subjects for the experiment.
          - `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.
              - …
      - `decision_metrics` ExperimentsCreateExperimentV2RequestDataAttributesDecisionMetricsItems[]: Metrics used to decide the experiment outcome.
        - `is_primary` boolean, required: Whether this is the experiment primary metric.
        - `metric_id` string, uuid, required: Decision metric UUID.
      - `decision_variant_key` string: Key of the variant selected in the experiment decision.
      - `events_end_date` string, date-time, nullable: End of the time window for metric events.
      - `events_start_date` string, date-time, nullable: Start of the time window for metric events.
      - `experiment_type` string: Kind of experiment. STANDARD is an ordinary experiment. Other values, such as CANARY and HOLDOUT, identify experiments owned by another workflow. New kinds may be added; treat unknown values as non-standard.
      - `hypothesis` string: Expected effect that the experiment is intended to test.
      - `migration_metadata` unknown
      - `name` string: Display name of the experiment.
      - `pipeline_table_suffix` string: Suffix used to identify the experiment's pipeline output table.
      - `protocol_id` string: ID of the protocol associated with the experiment.
      - `related_links` ExperimentsCreateExperimentV2RequestDataAttributesRelatedLinksItems[]: Links to supporting material for the experiment.
        - `id` string, nullable: Link ID. Omit it when adding a link.
        - `title` string, nullable: Optional display title.
        - `url` string, required: Absolute URL.
      - `results_last_updated` string, date-time, nullable: Time of the most recent update to the experiment's results.
      - `split_by_properties` ExperimentsExperimentV2DTODataAttributesSplitByPropertiesItems[]: Properties used to split the experiment results into groups.
        - `column_name` string, required: Exposure field or Warehouse column used for the analysis dimension.
        - `column_type` 'varchar' | 'int' | 'double' | 'boolean' | 'varchar_array' | 'int_array' | 'double_array' | 'raw' | 'STRING' | 'INTEGER' | 'FLOAT' | 'BOOLEAN' | 'DATE' | 'TIMESTAMP', required: Type of the Datadog exposure field or Warehouse column.
        - `id` string, required: Read-only property ID. Omit it from POST and PATCH; writes identify properties by column_name.
        - `name` string, required: Display name for the analysis dimension.
      - `status` 'DRAFT' | 'SCHEDULED' | 'IN_PROGRESS' | 'READY_FOR_DECISION' | 'DECISION_MADE' | 'CANCELLED' | 'UNKNOWN': Current stage in the experiment lifecycle.
      - `structured_metadata` ExperimentsStructuredMetadataResponse[]: Values of structured metadata fields attached to the experiment.
        - `enum_values` string[]: Selected values for an enumerated metadata field.
        - `field_display_name` string: Display name of the metadata field.
        - `field_key` string, required: Key that identifies the metadata field.
        - `field_type` 'FREETEXT' | 'ENUM': Type of value stored in the structured metadata field.
        - `freetext_value` string: Text value for a free-text metadata field.
      - `subject_type_id` string, nullable: ID of the subject type used by this configuration.
      - `summary` string: Summary text recorded for the experiment.
      - `tags` string[]: Tags attached to the experiment.
      - `teams` string[]: Teams associated with the experiment.
      - `traffic_exposure` ExperimentsPatchExperimentV2ResponseDataAttributesTrafficExposure: Traffic exposure fraction or schedule configured for the experiment.
        - `fraction` number, double: STATIC exposure fraction. Draft experiments can change this value. After start only warehouse experiments without a Datadog flag can change a STATIC fraction through the public API.
        - `mode` 'STATIC' | 'STEPS', required: Whether exposure uses a fixed fraction or a sequence of steps.
        - `steps` ExperimentsCreateExperimentV2RequestDataAttributesTrafficExposureStepsItems[]: Configured exposure plan rather than wall-clock history. At least two steps must have strictly increasing fractions and no gaps. Warehouse steps start at assignments_start_date and can use different durations. New Datadog plans have at most five steps and a first fraction above zero. Their nonfinal durations must be equal and exclude time paused. Datadog steps start with the experiment. Running warehouse experiments can replace step fractions, durations, and the exposure mode. After start, Datadog exposure plans cannot change through the public API. The final duration is null and its fraction holds until assignment ends.
          - `duration_ms` integer, nullable, required: Positive step duration in milliseconds. Datadog durations exclude pauses. Send null for the final step.
          - `fraction` number, double, required: Fraction of traffic exposed during this step.
      - `updated_at` string, date-time: Time when this resource was last updated.
      - `variants` ExperimentsExperimentV2DTODataAttributesVariantsItems[]: Variants configured for the experiment.
        - `feature_flag_variant_id` string: Backing feature flag variant ID. Present for Datadog feature flag experiments and omitted for Warehouse experiments.
        - `is_active` boolean, required: Whether this variant participates in the experiment.
        - `is_control` boolean, required: Whether this is the single control variant.
        - `key` string, required: Value recorded in exposure data for this variant.
        - `name` string, nullable: Display name of the experiment variant.
        - `weight` number, double, required: Traffic allocation percentage.
      - `warehouse_exposure_configuration` ExperimentsPatchExperimentV2ResponseDataAttributesWarehouseExposureConfiguration, nullable: Warehouse exposure model and settings used to identify experiment assignments.
        - `entry_point` ExperimentsWarehouseEntryPoint, nullable, required: Optional Warehouse measure that scopes analyzed subjects.
          - `filters` ExperimentsWarehouseExposureFilter[], required: Complete ordered Warehouse entry-point filter set.
            - `operation` 'IS' | 'IS_NOT', required: Comparison applied by the warehouse entry-point filter.
            - `property_id` string, required: Warehouse property UUID.
            - `values` string[], required: Ordered values used by the filter.
          - `measure_id` string, required: Warehouse measure UUID.
        - `experiment_key` string, nullable, required: Warehouse experiment key. Reads can return null for incomplete configuration; configuration writes require a value.
        - `exposure_sql_model_id` string, required: ID of the exposure SQL model that provides assignment data.
    - `id` string, uuid, required: Identifier of the experiment.
    - `type` 'experiments', required: Experiments resource type.
  - `meta` ExperimentsPatchExperimentV2MetaDTO: Refresh requirements and warnings returned by an experiment update.
    - `needs_pipeline_refresh` boolean, required: Whether this edit needs a full or non-full pipeline run. This operation does not start the run. A later false value does not clear a refresh required by an earlier edit.
    - `refresh_endpoint` string: POST to this endpoint after finishing your edits. The full_refresh query parameter selects the required run type. Across multiple edits any full_refresh=true requirement takes priority.
    - `warnings` ExperimentsPatchExperimentV2MetaDTOWarningsItems[]: Warnings returned after the experiment update.
      - `code` string, required: Code that identifies the warning.
      - `detail` string, required: Explanation of the warning and its effect on the update.

## Other responses

- `400`: Invalid request: malformed field, a read-only attribute was sent, a referenced ID doesn't exist, an allocation change is not supported after start, or the resulting analysis configuration is invalid. May return multiple errors.
- `401`: Missing or invalid authentication (dd-api-key + dd-application-key headers, or a valid user session).
- `403`: Authenticated caller lacks the product_analytics_experiments_write permission, lacks permission to edit this experiment, or lacks feature-flag and environment read permissions for a Datadog-backed configuration.
- `404`: No experiment with this ID exists for the organization.
- `409`: The requested configuration is incompatible with the experiment, or a feature flag change requires explicit reset consent and a complete target configuration (codes: unsupported_configuration, feature_flag_change_requires_reset, or feature_flag_change_requires_complete_configuration).
- `415`: Request body sent with a media type other than application/json or application/vnd.api+json.
- `429`: Too many requests

---

[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/3f70db624329?raw)