Class ExperimentsApi

Archive an exposure SQL model. Archived models are hidden from the default list and are no longer refreshed for new feature flags. Experiments already reading from the model keep working. Archiving is how a model that is in use by an experiment, and therefore cannot be deleted, is retired.

Cancel an experiment, ending it without a winning variant. The experiment moves to CANCELLED status, the supplied reason is recorded in its conclusion as the decision reason, and the experiment is unlinked from the feature flag allocations that exposed it, which stops its exposure. An experiment that has already completed its rollout, had its code removed, or been canceled cannot be canceled again. Canceling is not reversible: an experiment cannot be returned to a running state afterward. It is also not idempotent: canceling an already-canceled experiment returns 409, so a retry after a timeout cannot be distinguished from a cancellation made by someone else.

Conclude an experiment on a winning variant. The experiment moves to DECISION_MADE status, the outcome is recorded in its conclusion, and for a flag-backed experiment the winning variant is rolled out to 100% of the linked feature flag allocation. decision_variant_key must match a variant in the experiment. Only an experiment that is currently running or ready for a decision can be concluded. Concluding is not reversible and is not idempotent: concluding an already-concluded experiment returns 409.

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.

Create a non-decision metric group. The optional metrics array is ordered. Decision groups remain managed through decision_metrics on the experiment resource. This operation does not synchronously recompute results.

Copy a metric collection into a new non-decision metric group. The group is a request-time snapshot: later changes to the collection do not affect the experiment. Metric order is preserved. The operation is not idempotent, and incompatible or empty collections are rejected without creating a group.

Create an exposure SQL model. Requires at least one subject type. The warehouse connection is resolved from the organization, which has exactly one.

Create a metric. The metric's type is derived from the aggregation shape: a numerator alone is SIMPLE, a numerator with a denominator is RATIO, and a percentile aggregation is PERCENTILE. Warehouse aggregations reference measures by UUID. Property filters use property_id or measure_id UUIDs returned by the same metric SQL model; every reference must belong to the aggregation's data source. The is_certified attribute is rejected. Certification cannot be changed through this endpoint.

Create metric collection.

Create a metric SQL model. Requires at least one subject type, whose subject_type_id must already exist for the organization (list them with GET /api/v2/experiments/subject-types). The model is created against the organization's warehouse connection, which is resolved server-side. Only customer-defined measures belong in measures. The response provides unique_subject_count_measure_id for each subject type and event_count_measure_id for use in metric aggregations. column_type is required for every measure and property. Certification is read-only and cannot be changed through this endpoint.

Create a subject type for the organization.

Delete an experiment and its linked feature flag allocations in one database transaction. After deletion, the experiment is no longer returned by the API. If the transaction fails, neither the experiment nor its allocations are deleted. Deleting an experiment cannot be undone.

Delete a non-decision metric group and its memberships. Decision groups remain managed through the experiment resource. This operation does not start a pipeline. Read experiment results after deletion to check stale metadata, then explicitly refresh results when required.

Delete a metric. Certified metrics are read-only through this endpoint. The record is soft-deleted and stops appearing in reads. A metric still referenced by an experiment cannot be deleted; detach it from those experiments first.

Delete metric collection.

Delete a subject type. The record is soft-deleted and stops appearing in reads. The call is idempotent: deleting the same subject type again also returns 204. The organization's default subject type cannot be deleted; make another one the default first. A subject type that experiments, exposure SQL models, metric SQL models or protocols still reference cannot be deleted either; the refusal names the blockers.

Get a complete experiment by ID. The response includes structured metadata, related links, and, when a complete setup exists, decision metrics, variants, warehouse_exposure_configuration, datadog_flag_configuration, STATIC or STEPS traffic exposure, and assignment and event dates. STEPS describes the configured plan rather than wall-clock history; Datadog step durations exclude pauses. The list endpoint omits these setup details.

Get the effective public statistical analysis settings for an experiment. has_custom_analysis_settings compares only settings the caller can edit; protocol-required differences from company defaults do not make the plan custom.

Get the diagnostics produced by an experiment's latest analysis run. Each diagnostic includes its category, and the response includes an overall diagnostic or pipeline lifecycle status.

Get a draft, published, or archived experiment protocol by ID.

Get an experiment's computed results: per-variant statistical analysis for the latest successful run. A historical run cannot be selected. Unavailable analysis statistics, including p_value and confidence_interval, are omitted. The numerator, denominator, and variant_metric_value fields can be null when their values are unavailable. Do not treat an omitted or null value as zero.

Get an experiment's traffic summary: per-variant exposure counts and a sample-ratio-mismatch flag (is_traffic_imbalanced). SRM statistics live on the diagnostics endpoint.

Get an exposure SQL model. Returns a single model by its ID for the organization, including its subject types and properties.

Get a metric. Returns a single experiment metric by its ID for the organization.

Get metric collection.

Get a metric SQL model. Returns a single model by its ID for the organization, including its subject types, measures and properties.

Get a subject type. Returns a single subject type by its ID for the organization.

List every decision and non-decision metric group attached to an experiment. Metric references are returned in their stored order. An incomplete draft can have no decision group and returns only the groups that exist.

List draft, published, and archived experiment protocols. Omit filter[status] to return all statuses. Only published protocols can be used to create experiments.

List experiments. Returns a paginated list of experiments and their structured metadata for the organization. Supports filtering and pagination. Use Get experiment for variants, decision metrics, traffic exposure, and assignment configuration.

List exposure SQL models. Returns a paginated list of the SQL models that experiment exposures are read from for the organization. Models maintained by Datadog are not included: they cannot be modified and cannot be used as an experiment's assignment source.

List metric collections for the organization. Collections are reusable ordered metric sets; attaching one to an experiment creates an independent snapshot.

List metric SQL models. Returns a paginated list of the SQL models that metrics are defined on for the organization.

List metrics. Returns a paginated list of the experiment metrics defined for the organization.

List subject types. Returns a paginated list of the subject types defined for the organization.

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.

Update mutable fields on a subject type. Only the fields present in the body are changed. Any subject type can be updated, including the organization's default one, but the is_default flag itself is read-only here: which subject type is the default cannot be changed through this endpoint.

Request a results refresh for one experiment. HTTP 202 confirms acceptance, not completed results. The response identifies the experiment and does not include a job ID. Read experiment results to check freshness. A request while a refresh is queued or running returns 409. After completion, another request can start another refresh.

Trigger a results refresh across the organization's active experiments. Returns the count of experiments whose refresh was triggered (meta.experiments_updated) plus a per-experiment breakdown of what happened to each (meta.results).

Make this subject type the organization's default. Experiment creation uses the default when the request names no subject type. Promoting one subject type demotes the previous default in the same transaction, so the organization always has exactly one. The call is idempotent: promoting the current default succeeds and changes nothing. There is no matching demote, because an organization cannot have no default; promote a different subject type instead.

Start an experiment. The experiment is started exactly as it is configured; this endpoint accepts no attributes, and a request body carrying any is rejected rather than ignored. Set the run window, duration, or variants with PATCH /api/v2/experiments/{experiment_id} before starting. An unconfigured draft returns HTTP 409. Configure either warehouse_exposure_configuration or datadog_flag_configuration, plus the required experiment fields, before starting. Start validation errors can include meta.configuration_pointer to identify a field on the experiment to correct. For a flag-backed experiment this enables the linked feature flag's environment, clears any stored variant override on it, and starts the allocation's rollout. The request is idempotent: an experiment that is already running or ready for a decision still returns 204, so a retry after a timeout is safe. One exception: an experiment scheduled to start is accepted only when it is backed by your own feature flag; a Datadog-flag experiment in that state returns 409 because its stored state and flag allocation disagree. Cancel and conclude are not idempotent and return 409 when repeated.

Unarchive an exposure SQL model. Restores an archived model to the default list.

Update selected statistical analysis settings. Omitted attributes remain unchanged and nullable attributes can be cleared with null. Protocol-locked settings cannot be changed.

Update a non-decision metric group. Omitted attributes are unchanged; a supplied metrics array is the complete ordered replacement. Decision groups remain managed through the experiment resource. This operation does not synchronously recompute results.

Replace an exposure SQL model. This is a full replacement and is destructive: any subject type or property not present in the body is deleted, and properties are matched on name, column_name and column_type together, so changing one of those replaces the property rather than editing it. Send the complete set you want to keep. Anything removed is listed under meta.removed_subject_type_ids and meta.removed_property_names in the response. The warehouse connection is not settable and is left as stored.

Update a metric. Certified metrics are read-only through this endpoint. This is a partial update: every attribute is optional and an omitted attribute keeps its stored value, so a body carrying only the fields being changed is enough. guardrail_cutoff_threshold is nullable -- send null to clear it, omit it to leave it alone. Omitting the aggregation leaves the metric's definition untouched; supplying one replaces it wholesale, and the metric's type is re-derived from the shape supplied. Property filters use property_id or measure_id UUIDs from the aggregation's data source. Attributes that are computed rather than stored (short_id, metric_type, certified_at, experiment_count, created_at, updated_at) are rejected rather than ignored, so a body copied from GET must have them removed. The is_certified attribute is rejected. Certification cannot be changed through this endpoint.

Update metric collection.

Replace a metric SQL model. This is a destructive full replace: subject types, customer-defined measures, and properties absent from the body are deleted, so send the complete set. Properties are matched by name; changing a property's column, type, or description preserves its ID. column_type is required for every measure and property. Removing a measure or property that an active metric references returns 409 Conflict. Server-generated IDs returned by GET are read-only and can be left in a replayed body. The response reports removals in meta.deleted_subject_types, meta.deleted_measures, and meta.deleted_properties. Certification is read-only. Certified models cannot be replaced through this endpoint.