Create a draft experiment. name is required. structured_metadata identifies each metadata field by field_key; use freetext_value for free-text fields and enum_values for enum fields. When this attribute is present, the request must include a value for every required metadata field. When protocol_id is present, the published protocol supplies the subject type, decision metrics, analysis-plan defaults, and configuration and enforcement baselines. The request may also include hypothesis, tags, teams, related links, and assignment or event date overrides that satisfy the protocol’s duration rules; omit subject_type_id, decision_metrics, variants, warehouse_exposure_configuration, datadog_flag_configuration, traffic_exposure, split_by_properties, and structured_metadata. The protocol association cannot be changed after creation. Without protocol_id, a complete Warehouse or Datadog configuration saves the experiment and its configuration in one transaction. For Datadog flag configuration, send name, subject_type_id, decision_metrics, variants, traffic_exposure, assignments_start_date, assignments_end_date, events_start_date, and events_end_date. The four date fields can be null. Inside datadog_flag_configuration, send feature_flag_id, environment_id, targeting_rules, and entry_point. Use targeting_rules: [] and entry_point: null when unused. This creates one saved draft allocation that does not serve traffic. Omit all configuration fields to create an experiment without an allocation. This endpoint is not idempotent.
This endpoint requires the product_analytics_experiments_write permission.
OAuth apps require the product_analytics_experiments_write authorization scope to access this endpoint.
Identifier of the Datadog feature flag used by the experiment.
reset_on_feature_flag_change
boolean
Accepted on create but has no effect.
targeting_rules [required]
[object]
Use an empty array when no targeting rules apply.
conditions [required]
[ <oneOf>]
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.
Object 1
object
A condition that uses a saved filter. Inline fields must be omitted or null.
saved_filter_id [required]
uuid
Saved-filter UUID.
Object 2
object
An inline condition. The saved_filter_id field must be omitted or null.
attribute [required]
string
Attribute to evaluate.
operator [required]
enum
Required with attribute and value for an inline condition; omit when saved_filter_id is set.
Allowed enum values: LT,LTE,GT,GTE,MATCHES,NOT_MATCHES,ONE_OF,NOT_ONE_OF,IS_NULL,EQUALSShow 6 more,SEMVER_EQ,SEMVER_NEQ,SEMVER_LT,SEMVER_LTE,SEMVER_GT,SEMVER_GTE
value [required]
[string]
Values used by the operator. Every operator requires at least one value.
decision_metrics
[object]
Metrics selected to support the experiment decision.
is_primary [required]
boolean
Whether this is the experiment primary metric.
metric_id [required]
uuid
Decision metric UUID.
events_end_date
date-time
End of the window metric events are read from. Optional; must be after events_start_date.
events_start_date
date-time
Start of the window metric events are read from. Optional; must fall within the assignments window.
hypothesis
string
What the experiment is expected to show. Optional and free-form.
migration_metadata
Metadata associated with migration of this resource.
name [required]
string
Display name for the experiment. The only required attribute: a request carrying nothing but a name is accepted.
protocol_id
string
Published protocol whose defaults create this draft. May be combined with hypothesis, tags, teams, related links, and date overrides. Omit subject_type_id, decision_metrics, variants, warehouse_exposure_configuration, datadog_flag_configuration, traffic_exposure, and structured_metadata.
related_links
[object]
External links associated with the experiment.
id
string
Link ID. Omit it when adding a link.
title
string
Optional display title.
url [required]
string
Absolute URL.
split_by_properties
[object]
Complete Datadog split-by selection. Identify each property by column_name. Omit this field to copy organization defaults.
column_name [required]
string
Exposure field that identifies the property.
column_type
enum
Data type of the column evaluated by the entry-point filter.
Allowed enum values: varchar,int,double,boolean,varchar_array,int_array,double_array,raw
name
string
Optional display name. Defaults to column_name for a new property.
structured_metadata
[object]
Custom metadata fields and their values for the experiment.
enum_values
[string]
Selected values for an enumerated metadata field.
field_key [required]
string
Key that identifies the metadata field.
freetext_value
string
Text value for a free-text metadata field.
subject_type_id
uuid
Canonical ID of an existing subject type. Optional; defaults to the organization default.
summary
string
Summary of the experiment. Optional and free-form.
tags
[string]
Non-team tag names to apply. Optional.
teams
[string]
Team handles that own the experiment. Optional.
traffic_exposure
object
Traffic exposure fraction or schedule configured for the experiment.
fraction
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 [required]
enum
Whether exposure uses a fixed fraction or a sequence of steps.
Allowed enum values: STATIC,STEPS
steps
[object]
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 [required]
int64
Positive step duration in milliseconds. Datadog durations exclude pauses. Send null for the final step.
fraction [required]
double
Fraction of traffic exposed during this step.
variants
[object]
Variants selected for the experiment and their traffic allocations.
feature_flag_variant_id
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 [required]
boolean
Whether this is the single control variant.
key [required]
string
Assignment value. Datadog flag variant keys are server-owned.
name
string
Display name. Datadog flag variant names are server-owned.
weight [required]
double
Traffic allocation percentage. Existing variant weights cannot change through the public API after the experiment starts.
warehouse_exposure_configuration
object
Warehouse model and experiment key used to read assignment data.
entry_point [required]
object
Optional Warehouse measure that scopes analyzed subjects.
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
[object]
Rules that select subjects for the experiment.
conditions [required]
[ <oneOf>]
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.
Object 1
object
A condition that uses a saved filter. Inline fields must be omitted or null.
saved_filter_id [required]
uuid
Saved-filter UUID.
Object 2
object
An inline condition. The saved_filter_id field must be omitted or null.
attribute [required]
string
Attribute to evaluate.
operator [required]
enum
Required with attribute and value for an inline condition; omit when saved_filter_id is set.
Allowed enum values: LT,LTE,GT,GTE,MATCHES,NOT_MATCHES,ONE_OF,NOT_ONE_OF,IS_NULL,EQUALSShow 6 more,SEMVER_EQ,SEMVER_NEQ,SEMVER_LT,SEMVER_LTE,SEMVER_GT,SEMVER_GTE
value [required]
[string]
Values used by the operator. Every operator requires at least one value.
decision_metrics
[object]
Metrics used to decide the experiment outcome.
is_primary [required]
boolean
Whether this is the experiment primary metric.
metric_id [required]
uuid
Decision metric UUID.
decision_variant_key
string
Key of the variant selected in the experiment decision.
events_end_date
date-time
End of the time window for metric events.
events_start_date
date-time
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
Metadata retained for resources imported from another system.
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
[object]
Links to supporting material for the experiment.
id
string
Link ID. Omit it when adding a link.
title
string
Optional display title.
url [required]
string
Absolute URL.
results_last_updated
date-time
Time of the most recent update to the experiment's results.
split_by_properties
[object]
Properties used to split the experiment results into groups.
column_name [required]
string
Exposure field or Warehouse column used for the analysis dimension.
column_type [required]
enum
Type of the Datadog exposure field or Warehouse column.
Allowed enum values: varchar,int,double,boolean,varchar_array,int_array,double_array,raw,STRING,INTEGERShow 4 more,FLOAT,BOOLEAN,DATE,TIMESTAMP
id [required]
string
Read-only property ID. Omit it from POST and PATCH; writes identify properties by column_name.
name [required]
string
Display name for the analysis dimension.
status
enum
Current stage in the experiment lifecycle.
Allowed enum values: DRAFT,SCHEDULED,IN_PROGRESS,READY_FOR_DECISION,DECISION_MADE,CANCELLED,UNKNOWN
structured_metadata
[object]
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 [required]
string
Key that identifies the metadata field.
field_type
enum
Type of value stored in the structured metadata field.
Allowed enum values: FREETEXT,ENUM
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
Summary text recorded for the experiment.
tags
[string]
Tags attached to the experiment.
teams
[string]
Teams associated with the experiment.
traffic_exposure
object
Traffic exposure fraction or schedule configured for the experiment.
fraction
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 [required]
enum
Whether exposure uses a fixed fraction or a sequence of steps.
Allowed enum values: STATIC,STEPS
steps
[object]
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 [required]
int64
Positive step duration in milliseconds. Datadog durations exclude pauses. Send null for the final step.
fraction [required]
double
Fraction of traffic exposed during this step.
updated_at
date-time
Time when this resource was last updated.
variants
[object]
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 [required]
boolean
Whether this variant participates in the experiment.
is_control [required]
boolean
Whether this is the single control variant.
key [required]
string
Value recorded in exposure data for this variant.
name
string
Display name of the experiment variant.
weight [required]
double
Traffic allocation percentage.
warehouse_exposure_configuration
object
Warehouse exposure model and settings used to identify experiment assignments.
entry_point [required]
object
Optional Warehouse measure that scopes analyzed subjects.
## Draft with a Datadog feature flag
# Replace the resource IDs with IDs from your organization. The flag variants must belong to the specified flag. This request saves a draft allocation and does not start traffic.
# Use a Personal Access Token or Service Access Token exportDD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>"
# Curl command curl-XPOST"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" \
-H"Accept: application/json" \
-H"Content-Type: application/json" \
-H"Authorization: Bearer ${DD_BEARER_TOKEN}" \
-d@-<<EOF{
"data": {
"attributes": {
"name": "Checkout button test"
},
"type": "experiments"
}
}EOF ## Draft from a published protocol
# Replace protocol_id with a published protocol ID from your organization. The protocol supplies the configuration and its rules. Do not copy the configuration fields from the other examples into this request.
# Use a Personal Access Token or Service Access Token exportDD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>"
# Curl command curl-XPOST"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" \
-H"Accept: application/json" \
-H"Content-Type: application/json" \
-H"Authorization: Bearer ${DD_BEARER_TOKEN}" \
-d@-<<EOF{
"data": {
"attributes": {
"name": "Checkout protocol test",
"protocol_id": "550e8400-e29b-41d4-a716-446655440040"
},
"type": "experiments"
}
}EOF ## Draft with warehouse assignments
# Replace the subject type, metric, and exposure SQL model IDs with compatible resources from your organization. The SQL model must provide assignments for checkout_button_test and the control and treatment variant keys. This request saves configuration and does not start analysis.
# Use a Personal Access Token or Service Access Token exportDD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>"
