Language

English Français 日本語 한국어 Español

Datadog Site

Site help
US1 US3 US5 EU AP1 AP2 UK1 US1-FED US2-FED
This product is not supported for your selected Datadog site. ().

Get experiment

copy Copy pageCopied

GET 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

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. This endpoint requires the product_analytics_experiments_read permission.

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

Arguments

Path Parameters

Name

Type

Description

experiment_id [required]

string

The UUID of the experiment.

Response

OK

Response containing an experiment and its configuration.

Expand All

Field

Type

Description

data [required]

object

Experiment resource with its identifier and configuration.

attributes

object

Details of the experiment.

assignments_end_date

date-time

End of the time window for experiment assignments.

assignments_start_date

date-time

Start of the time window for experiment assignments.

concluded_at

date-time

Time when the experiment was concluded.

conclusion

object

Outcome and supporting text recorded when the experiment is concluded.

decision_reason

string

Reason for the recorded decision.

outcome

enum

Recorded experiment outcome. Allowed enum values: POSITIVE,NEGATIVE,NEUTRAL,INCONCLUSIVE,MISCONFIGURED,UNKNOWN

summary

string

Summary of the experiment conclusion.

created_at

date-time

Time when this resource was created.

datadog_flag_configuration

object

Feature flag, environment, and targeting configuration for the experiment.

allocation_key

string

Key of the feature flag allocation linked to the experiment.

entry_point [required]

object

Datadog measure and filters used to select analyzed subjects.

filters [required]

[array]

Complete Datadog OR-of-ANDs entry-point filter expression.

measure_id [required]

string

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

[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,EQUALS

Show 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,INTEGER

Show 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.

filters [required]

[object]

Complete ordered Warehouse entry-point filter set.

operation [required]

enum

Comparison applied by the warehouse entry-point filter. Allowed enum values: IS,IS_NOT

property_id [required]

string

Warehouse property UUID.

values [required]

[string]

Ordered values used by the filter.

measure_id [required]

string

Warehouse measure UUID.

experiment_key [required]

string

Warehouse experiment key. Reads can return null for incomplete configuration; configuration writes require a value.

exposure_sql_model_id [required]

string

ID of the exposure SQL model that provides assignment data.

id [required]

uuid

Identifier of the experiment.

type [required]

enum

Experiments resource type. Allowed enum values: experiments

default: experiments

{
  "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"
  }
}

Malformed experiment ID (not a valid UUID).

API error response.

Expand All

Field

Type

Description

errors [required]

[object]

A list of errors.

detail

string

A human-readable explanation specific to this occurrence of the error.

meta

object

Non-standard meta-information about the error

source

object

References to the source of the error.

header

string

A string indicating the name of a single request header which caused the error.

parameter

string

A string indicating which URI query parameter caused the error.

pointer

string

A JSON pointer to the value in the request document that caused the error.

status

string

Status code of the response.

title

string

Short human-readable summary of the error.

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

Missing or invalid authentication (dd-api-key + dd-application-key headers, or a valid user session).

API error response.

Expand All

Field

Type

Description

errors [required]

[object]

A list of errors.

detail

string

A human-readable explanation specific to this occurrence of the error.

meta

object

Non-standard meta-information about the error

source

object

References to the source of the error.

header

string

A string indicating the name of a single request header which caused the error.

parameter

string

A string indicating which URI query parameter caused the error.

pointer

string

A JSON pointer to the value in the request document that caused the error.

status

string

Status code of the response.

title

string

Short human-readable summary of the error.

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

Authenticated caller lacks the product_analytics_experiments_read permission, or lacks feature-flag and environment read permissions for a Datadog-backed configuration.

API error response.

Expand All

Field

Type

Description

errors [required]

[object]

A list of errors.

detail

string

A human-readable explanation specific to this occurrence of the error.

meta

object

Non-standard meta-information about the error

source

object

References to the source of the error.

header

string

A string indicating the name of a single request header which caused the error.

parameter

string

A string indicating which URI query parameter caused the error.

pointer

string

A JSON pointer to the value in the request document that caused the error.

status

string

Status code of the response.

title

string

Short human-readable summary of the error.

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

No experiment with this ID exists for the organization.

API error response.

Expand All

Field

Type

Description

errors [required]

[object]

A list of errors.

detail

string

A human-readable explanation specific to this occurrence of the error.

meta

object

Non-standard meta-information about the error

source

object

References to the source of the error.

header

string

A string indicating the name of a single request header which caused the error.

parameter

string

A string indicating which URI query parameter caused the error.

pointer

string

A JSON pointer to the value in the request document that caused the error.

status

string

Status code of the response.

title

string

Short human-readable summary of the error.

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

The stored assignment configuration cannot be represented losslessly by this API (unsupported_configuration).

API error response.

Expand All

Field

Type

Description

errors [required]

[object]

A list of errors.

detail

string

A human-readable explanation specific to this occurrence of the error.

meta

object

Non-standard meta-information about the error

source

object

References to the source of the error.

header

string

A string indicating the name of a single request header which caused the error.

parameter

string

A string indicating which URI query parameter caused the error.

pointer

string

A JSON pointer to the value in the request document that caused the error.

status

string

Status code of the response.

title

string

Short human-readable summary of the error.

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

Too many requests

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

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

Code Example

                  # 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 GET "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 "Authorization: Bearer ${DD_BEARER_TOKEN}"