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 protocol

copy Copy pageCopied

GET https://api.ap1.datadoghq.com/api/v2/experiments/protocols/{protocol_id}https://api.ap2.datadoghq.com/api/v2/experiments/protocols/{protocol_id}https://api.datadoghq.eu/api/v2/experiments/protocols/{protocol_id}https://api.ddog-gov.com/api/v2/experiments/protocols/{protocol_id}https://api.us2.ddog-gov.com/api/v2/experiments/protocols/{protocol_id}https://api.uk1.datadoghq.com/api/v2/experiments/protocols/{protocol_id}https://api.datadoghq.com/api/v2/experiments/protocols/{protocol_id}https://api.us3.datadoghq.com/api/v2/experiments/protocols/{protocol_id}https://api.us5.datadoghq.com/api/v2/experiments/protocols/{protocol_id}

Overview

Get a draft, published, or archived experiment protocol by ID. 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

protocol_id [required]

string

The UUID of the protocol.

Response

OK

Response containing the protocol.

Expand All

Field

Type

Description

data [required]

object

JSON:API resource containing the protocol identity and fields.

attributes

object

Settings and defaults supplied by the protocol.

analysis_plan

object

Default statistical settings supplied by the protocol.

compute_cuped

boolean

Whether to use pre-experiment data to reduce variance with CUPED.

confidence_interval_method

string

Statistical method used to calculate confidence intervals.

confidence_level

double

Confidence level used by the statistical analysis.

multiple_testing_correction_method

string

Method used to adjust for testing multiple metrics.

assignment_source_default_properties

[object]

Default properties supplied by the protocol's assignment source.

column_name

string

Source column that supplies this assignment property.

column_type

string

Data type of the source column.

name

string

Display name of the assignment source property.

assignment_source_id

string

ID of the assignment source selected by the protocol.

default_duration_days

int64

Default experiment duration supplied by the protocol, in days.

description

string

Text that explains the protocol.

enforcement

object

Controls that determine which protocol settings can be changed in an experiment.

confidence_interval_method

string

LOCKED prevents changes to confidence interval method. EDITABLE permits changes.

confidence_level

string

LOCKED prevents changes to confidence level. EDITABLE permits changes.

cuped_calculation

string

LOCKED prevents changes to CUPED variance reduction. EDITABLE permits changes.

default_duration

string

LOCKED prevents changes to default duration. EDITABLE permits changes.

environment

string

LOCKED prevents changes to environment. EDITABLE permits changes.

flag_source

string

LOCKED prevents changes to feature flag source. EDITABLE permits changes.

multiple_testing_correction

string

LOCKED prevents changes to multiple testing correction. EDITABLE permits changes.

notifications

string

LOCKED prevents changes to notifications. EDITABLE permits changes.

primary_metric

string

LOCKED prevents changes to primary metric. EDITABLE permits changes.

secondary_metrics

string

LOCKED prevents changes to secondary metrics. EDITABLE permits changes.

split_by_exploration_dimensions

string

LOCKED prevents changes to result exploration dimensions. EDITABLE permits changes.

subject_type

string

LOCKED prevents changes to subject type. EDITABLE permits changes.

targeting_rules

string

LOCKED prevents changes to targeting rules. EDITABLE permits changes.

traffic_exposure

string

LOCKED prevents changes to traffic exposure. EDITABLE permits changes.

warehouse_exposure_source

string

LOCKED prevents changes to warehouse exposure source. EDITABLE permits changes.

environment_id

string

ID of the feature flag environment used by the experiment.

exposure_schedule

object

Schedule that controls traffic exposure for experiments created from the protocol.

autostart

boolean

Whether the exposure schedule starts automatically.

guardrail_triggered_action

string

Action taken when a guardrail triggers during the exposure schedule.

rollout_steps

[object]

Ordered steps that define changes in traffic exposure.

exposure_ratio

double

Fraction of traffic exposed during this rollout step.

grouped_step_index

int64

Index of the group that contains this rollout step.

interval_ms

int64

Duration of this rollout step, in milliseconds.

is_pause_record

boolean

Whether this schedule entry represents a pause.

order_position

int64

Position of this entry in the ordered configuration.

selection_interval_ms

int64

Interval between traffic selections, in milliseconds.

strategy

string

Method used to increase traffic exposure over the schedule.

is_duration_required_to_start [required]

boolean

Whether the protocol requires a duration before an experiment can start.

is_equal_split_enforced [required]

boolean

Whether the protocol requires equal traffic allocation across variants.

is_metric_limit_enabled [required]

boolean

Whether the protocol limits the number of metrics.

is_minimum_duration_enabled [required]

boolean

Whether the protocol enforces a minimum experiment duration.

metric_groups [required]

[object]

Metric groups supplied by the protocol.

is_decision

boolean

Whether the group contains decision metrics.

metrics

[object]

Metrics included in this group.

metric_id [required]

uuid

Identifier of the metric to include in the collection.

name

string

Display name of the metric group.

metric_limit

int64

Maximum number of metrics allowed by the protocol.

migration_metadata

Metadata retained for resources imported from another system.

minimum_duration_unit

string

Unit used to express the protocol's minimum duration.

minimum_duration_value

int64

Minimum experiment duration in the specified unit.

name [required]

string

Display name of the protocol.

primary_metric

object

Subject type selected by the protocol.

id

string

ID of the subject type.

name

string

Display name of the subject type.

primary_metric_id

string

ID of the primary metric supplied by the protocol.

published_at

date-time

Time when the protocol was published.

status [required]

enum

Publication status of the protocol. Allowed enum values: DRAFT,PUBLISHED,ARCHIVED

subject_type

object

Subject type selected by the protocol.

id

string

ID of the subject type.

name

string

Display name of the subject type.

subject_type_id

string

ID of the subject type used by this configuration.

targeting_rules

[object]

Rules that select subjects for the experiment.

conditions

[object]

Conditions that define this targeting rule.

attribute

string

Subject attribute evaluated by the targeting condition.

operator

string

Comparison applied to the subject attribute.

order_position

int64

Position of this entry in the ordered configuration.

saved_filter_id

string

ID of the saved filter used by this targeting condition.

value

[string]

Values compared with the subject attribute in this condition.

updated_at [required]

string

RFC3339 update time. Preserve all fractional seconds when passing this value as expected_updated_at.

id [required]

uuid

ID of the protocol.

type [required]

enum

Protocols resource type. Allowed enum values: protocols

default: protocols

{
  "data": {
    "attributes": {
      "analysis_plan": {
        "compute_cuped": false,
        "confidence_interval_method": "string",
        "confidence_level": "number",
        "multiple_testing_correction_method": "string"
      },
      "assignment_source_default_properties": [
        {
          "column_name": "string",
          "column_type": "string",
          "name": "string"
        }
      ],
      "assignment_source_id": "string",
      "default_duration_days": "integer",
      "description": "string",
      "enforcement": {
        "confidence_interval_method": "string",
        "confidence_level": "string",
        "cuped_calculation": "string",
        "default_duration": "string",
        "environment": "string",
        "flag_source": "string",
        "multiple_testing_correction": "string",
        "notifications": "string",
        "primary_metric": "string",
        "secondary_metrics": "string",
        "split_by_exploration_dimensions": "string",
        "subject_type": "string",
        "targeting_rules": "string",
        "traffic_exposure": "string",
        "warehouse_exposure_source": "string"
      },
      "environment_id": "string",
      "exposure_schedule": {
        "autostart": false,
        "guardrail_triggered_action": "string",
        "rollout_steps": [
          {
            "exposure_ratio": "number",
            "grouped_step_index": "integer",
            "interval_ms": "integer",
            "is_pause_record": false,
            "order_position": "integer"
          }
        ],
        "selection_interval_ms": "integer",
        "strategy": "string"
      },
      "is_duration_required_to_start": false,
      "is_equal_split_enforced": false,
      "is_metric_limit_enabled": false,
      "is_minimum_duration_enabled": false,
      "metric_groups": [
        {
          "is_decision": false,
          "metrics": [
            {
              "metric_id": "550e8400-e29b-41d4-a716-446655440000"
            }
          ],
          "name": "string"
        }
      ],
      "metric_limit": "integer",
      "migration_metadata": "undefined",
      "minimum_duration_unit": "string",
      "minimum_duration_value": "integer",
      "name": "Checkout conversion",
      "primary_metric": {
        "id": "string",
        "name": "string"
      },
      "primary_metric_id": "string",
      "published_at": "2019-09-19T10:00:00.000Z",
      "status": "PUBLISHED",
      "subject_type": {
        "id": "string",
        "name": "string"
      },
      "subject_type_id": "string",
      "targeting_rules": [
        {
          "conditions": [
            {
              "attribute": "string",
              "operator": "string",
              "order_position": "integer",
              "saved_filter_id": "string",
              "value": []
            }
          ]
        }
      ],
      "updated_at": "2026-01-01T00:00:00Z"
    },
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "type": "protocols"
  }
}

Bad Request

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

Unauthorized

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

Forbidden

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

Not Found

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 protocol_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/protocols/${protocol_id}" \
-H "Accept: application/json" \
-H "Authorization: Bearer ${DD_BEARER_TOKEN}"