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. ().

Archive experiment protocol

copy Copy pageCopied

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

Overview

Archive a draft or published protocol. Archived protocols cannot be edited or used to create new experiments. Existing experiments keep their settings. Archiving an already archived protocol returns 409. This endpoint requires the product_analytics_experiments_write permission.

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

Arguments

Path Parameters

Name

Type

Description

protocol_id [required]

string

The UUID of the protocol.

Query Strings

Name

Type

Description

expected_updated_at

string

The updated_at value from the last read. Include the full timestamp, with fractional seconds. Returns 409 if another write changed the protocol. Omit to skip this check.

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.

archived_at

date-time

Time when the protocol was archived. Omitted if it has not been archived.

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.

created_at [required]

date-time

Time when the protocol was created.

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

Always LOCKED. The server keeps this setting locked regardless of the supplied value.

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

Always LOCKED. The server keeps this setting locked regardless of the supplied value.

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

Always LOCKED. The server keeps this setting locked regardless of the supplied value.

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.

experiment_count

int64

Number of experiments in the organization that use this protocol, excluding deleted experiments. Omitted if the count cannot be retrieved. An omitted count does not mean zero.

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"
      },
      "archived_at": "2026-07-31T14:00:00Z",
      "assignment_source_default_properties": [
        {
          "column_name": "string",
          "column_type": "string",
          "name": "string"
        }
      ],
      "assignment_source_id": "string",
      "created_at": "2026-07-31T12:00:00Z",
      "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",
      "experiment_count": 0,
      "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"
  }
}

Invalid request or protocol settings.

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.

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 caller lacks the product_analytics_experiments_write permission.

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 protocol with this ID exists in 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 protocol is already archived or expected_updated_at is stale.

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

Internal Server Error

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

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