For AI agents: A markdown version of this page is available at https://dnd37xeb23o8n.cloudfront.net/stefon.simmons/docs-astro-web-10435/es/api/latest/experiments/patch-experiment.md. A documentation index is available at /llms.txt.
Language
Datadog site
PRECAUCIÓNEste producto no es compatible con el sitio Datadog seleccionado. (US1-FED).
PRECAUCIÓNEste producto no es compatible con el sitio Datadog seleccionado. (US2-FED).

Patch experiment

PATCHhttps://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}https://api.datadoghq.eu/api/v2/experiments/{experiment_id}https://api.ap1.datadoghq.com/api/v2/experiments/{experiment_id}https://api.ap2.datadoghq.com/api/v2/experiments/{experiment_id}https://api.uk1.datadoghq.com/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}

Descripción general

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.

This endpoint requires the product_analytics_experiments_write permission.

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

Argumentos

Parámetros de ruta

Nombre
Type
Descripción
experiment_id [required]
string

The UUID of the experiment.

Solicitud

Body Data (required)

Campo
Type
Descripción
data [required]
object

JSON:API resource containing the experiment identity and fields.

Respuesta

OK

Response containing the updated experiment, refresh requirements, and warnings.

Campo
Type
Descripción
data [required]
object

Experiment resource with its identifier and configuration.

meta
object

Refresh requirements and warnings returned by an experiment update.

Ejemplo de código

# Path parameters
export experiment_id="550e8400-e29b-41d4-a716-446655440000"

# Set your Datadog site and credentials
export DD_SITE="datadoghq.com"
# Use a Personal Access Token or Service Access Token
export DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>"

curl -X PATCH "https://api.${DD_SITE}/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
# Path parameters
export experiment_id="550e8400-e29b-41d4-a716-446655440000"

# Set your Datadog site and credentials
export DD_SITE="us3.datadoghq.com"
# Use a Personal Access Token or Service Access Token
export DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>"

curl -X PATCH "https://api.${DD_SITE}/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
# Path parameters
export experiment_id="550e8400-e29b-41d4-a716-446655440000"

# Set your Datadog site and credentials
export DD_SITE="us5.datadoghq.com"
# Use a Personal Access Token or Service Access Token
export DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>"

curl -X PATCH "https://api.${DD_SITE}/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
# Path parameters
export experiment_id="550e8400-e29b-41d4-a716-446655440000"

# Set your Datadog site and credentials
export DD_SITE="datadoghq.eu"
# Use a Personal Access Token or Service Access Token
export DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>"

curl -X PATCH "https://api.${DD_SITE}/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
# Path parameters
export experiment_id="550e8400-e29b-41d4-a716-446655440000"

# Set your Datadog site and credentials
export DD_SITE="ap1.datadoghq.com"
# Use a Personal Access Token or Service Access Token
export DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>"

curl -X PATCH "https://api.${DD_SITE}/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
# Path parameters
export experiment_id="550e8400-e29b-41d4-a716-446655440000"

# Set your Datadog site and credentials
export DD_SITE="ap2.datadoghq.com"
# Use a Personal Access Token or Service Access Token
export DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>"

curl -X PATCH "https://api.${DD_SITE}/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
# Path parameters
export experiment_id="550e8400-e29b-41d4-a716-446655440000"

# Set your Datadog site and credentials
export DD_SITE="uk1.datadoghq.com"
# Use a Personal Access Token or Service Access Token
export DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>"

curl -X PATCH "https://api.${DD_SITE}/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
# Path parameters
export experiment_id="550e8400-e29b-41d4-a716-446655440000"

# Set your Datadog site and credentials
export DD_SITE="ddog-gov.com"
# Use a Personal Access Token or Service Access Token
export DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>"

curl -X PATCH "https://api.${DD_SITE}/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
# Path parameters
export experiment_id="550e8400-e29b-41d4-a716-446655440000"

# Set your Datadog site and credentials
export DD_SITE="us2.ddog-gov.com"
# Use a Personal Access Token or Service Access Token
export DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>"

curl -X PATCH "https://api.${DD_SITE}/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