For AI agents: A markdown version of this page is available at https://dnd37xeb23o8n.cloudfront.net/jen.gilbert/astro-base/api/latest/experiments/replace-experiment-protocol.md. A documentation index is available at /llms.txt.
Language
Datadog site
CAUTIONThis product is not supported for your selected Datadog site. (US1-FED).
CAUTIONThis product is not supported for your selected Datadog site. (US2-FED).

Replace experiment protocol

PUThttps://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}https://api.datadoghq.eu/api/v2/experiments/protocols/{protocol_id}https://api.ap1.datadoghq.com/api/v2/experiments/protocols/{protocol_id}https://api.ap2.datadoghq.com/api/v2/experiments/protocols/{protocol_id}https://api.uk1.datadoghq.com/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}

Overview

Replace the template of a published protocol. Draft and archived protocols return 409. Send subject_type_id, all four required boolean settings, and metric_groups. Omitted optional template fields are cleared. Omitted enforcement keeps the existing locks.

Use primary_metric_id to select the primary metric. Use default_duration_days to set target_duration_days on experiments created from the protocol. The nested metric is_primary and analysis_plan.target_duration_days fields are rejected. An unchanged GET response can be sent as the request body. Response-only fields are ignored.

Independent configuration errors are returned together in the JSON:API errors array. Each error identifies the field in source.pointer. Earlier request and reference checks can stop on the first error. A failed request leaves the protocol unchanged. Changes apply to future experiments; existing experiments keep their settings.

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.

Request

Body Data (required)

Field
Type
Description
data [required]
object

JSON:API protocol request resource.

Response

OK

Response containing the protocol.

Field
Type
Description
data [required]
object

JSON:API resource containing the protocol identity and fields.

Code Example

Replace experiment protocol
# Path parameters
export protocol_id="550e8400-e29b-41d4-a716-446655440000"

# Set your Datadog site and credentials
export DD_SITE="datadoghq.com"
# Use a Personal Access Token or Service Access Token
export DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>"

curl -X PUT "https://api.${DD_SITE}/api/v2/experiments/protocols/${protocol_id}" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${DD_BEARER_TOKEN}" \
-d @- << EOF
{
  "data": {
    "attributes": {
      "is_duration_required_to_start": false,
      "is_equal_split_enforced": false,
      "is_metric_limit_enabled": false,
      "is_minimum_duration_enabled": false,
      "metric_groups": [],
      "subject_type_id": "c2b3d4e5-0000-0000-0000-000000000000"
    },
    "type": "protocols"
  }
}
EOF
# Path parameters
export protocol_id="550e8400-e29b-41d4-a716-446655440000"

# Set your Datadog site and credentials
export DD_SITE="us3.datadoghq.com"
# Use a Personal Access Token or Service Access Token
export DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>"

curl -X PUT "https://api.${DD_SITE}/api/v2/experiments/protocols/${protocol_id}" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${DD_BEARER_TOKEN}" \
-d @- << EOF
{
  "data": {
    "attributes": {
      "is_duration_required_to_start": false,
      "is_equal_split_enforced": false,
      "is_metric_limit_enabled": false,
      "is_minimum_duration_enabled": false,
      "metric_groups": [],
      "subject_type_id": "c2b3d4e5-0000-0000-0000-000000000000"
    },
    "type": "protocols"
  }
}
EOF
# Path parameters
export protocol_id="550e8400-e29b-41d4-a716-446655440000"

# Set your Datadog site and credentials
export DD_SITE="us5.datadoghq.com"
# Use a Personal Access Token or Service Access Token
export DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>"

curl -X PUT "https://api.${DD_SITE}/api/v2/experiments/protocols/${protocol_id}" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${DD_BEARER_TOKEN}" \
-d @- << EOF
{
  "data": {
    "attributes": {
      "is_duration_required_to_start": false,
      "is_equal_split_enforced": false,
      "is_metric_limit_enabled": false,
      "is_minimum_duration_enabled": false,
      "metric_groups": [],
      "subject_type_id": "c2b3d4e5-0000-0000-0000-000000000000"
    },
    "type": "protocols"
  }
}
EOF
# Path parameters
export protocol_id="550e8400-e29b-41d4-a716-446655440000"

# Set your Datadog site and credentials
export DD_SITE="datadoghq.eu"
# Use a Personal Access Token or Service Access Token
export DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>"

curl -X PUT "https://api.${DD_SITE}/api/v2/experiments/protocols/${protocol_id}" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${DD_BEARER_TOKEN}" \
-d @- << EOF
{
  "data": {
    "attributes": {
      "is_duration_required_to_start": false,
      "is_equal_split_enforced": false,
      "is_metric_limit_enabled": false,
      "is_minimum_duration_enabled": false,
      "metric_groups": [],
      "subject_type_id": "c2b3d4e5-0000-0000-0000-000000000000"
    },
    "type": "protocols"
  }
}
EOF
# Path parameters
export protocol_id="550e8400-e29b-41d4-a716-446655440000"

# Set your Datadog site and credentials
export DD_SITE="ap1.datadoghq.com"
# Use a Personal Access Token or Service Access Token
export DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>"

curl -X PUT "https://api.${DD_SITE}/api/v2/experiments/protocols/${protocol_id}" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${DD_BEARER_TOKEN}" \
-d @- << EOF
{
  "data": {
    "attributes": {
      "is_duration_required_to_start": false,
      "is_equal_split_enforced": false,
      "is_metric_limit_enabled": false,
      "is_minimum_duration_enabled": false,
      "metric_groups": [],
      "subject_type_id": "c2b3d4e5-0000-0000-0000-000000000000"
    },
    "type": "protocols"
  }
}
EOF
# Path parameters
export protocol_id="550e8400-e29b-41d4-a716-446655440000"

# Set your Datadog site and credentials
export DD_SITE="ap2.datadoghq.com"
# Use a Personal Access Token or Service Access Token
export DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>"

curl -X PUT "https://api.${DD_SITE}/api/v2/experiments/protocols/${protocol_id}" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${DD_BEARER_TOKEN}" \
-d @- << EOF
{
  "data": {
    "attributes": {
      "is_duration_required_to_start": false,
      "is_equal_split_enforced": false,
      "is_metric_limit_enabled": false,
      "is_minimum_duration_enabled": false,
      "metric_groups": [],
      "subject_type_id": "c2b3d4e5-0000-0000-0000-000000000000"
    },
    "type": "protocols"
  }
}
EOF
# Path parameters
export protocol_id="550e8400-e29b-41d4-a716-446655440000"

# Set your Datadog site and credentials
export DD_SITE="uk1.datadoghq.com"
# Use a Personal Access Token or Service Access Token
export DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>"

curl -X PUT "https://api.${DD_SITE}/api/v2/experiments/protocols/${protocol_id}" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${DD_BEARER_TOKEN}" \
-d @- << EOF
{
  "data": {
    "attributes": {
      "is_duration_required_to_start": false,
      "is_equal_split_enforced": false,
      "is_metric_limit_enabled": false,
      "is_minimum_duration_enabled": false,
      "metric_groups": [],
      "subject_type_id": "c2b3d4e5-0000-0000-0000-000000000000"
    },
    "type": "protocols"
  }
}
EOF
# Path parameters
export protocol_id="550e8400-e29b-41d4-a716-446655440000"

# Set your Datadog site and credentials
export DD_SITE="ddog-gov.com"
# Use a Personal Access Token or Service Access Token
export DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>"

curl -X PUT "https://api.${DD_SITE}/api/v2/experiments/protocols/${protocol_id}" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${DD_BEARER_TOKEN}" \
-d @- << EOF
{
  "data": {
    "attributes": {
      "is_duration_required_to_start": false,
      "is_equal_split_enforced": false,
      "is_metric_limit_enabled": false,
      "is_minimum_duration_enabled": false,
      "metric_groups": [],
      "subject_type_id": "c2b3d4e5-0000-0000-0000-000000000000"
    },
    "type": "protocols"
  }
}
EOF
# Path parameters
export protocol_id="550e8400-e29b-41d4-a716-446655440000"

# Set your Datadog site and credentials
export DD_SITE="us2.ddog-gov.com"
# Use a Personal Access Token or Service Access Token
export DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>"

curl -X PUT "https://api.${DD_SITE}/api/v2/experiments/protocols/${protocol_id}" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${DD_BEARER_TOKEN}" \
-d @- << EOF
{
  "data": {
    "attributes": {
      "is_duration_required_to_start": false,
      "is_equal_split_enforced": false,
      "is_metric_limit_enabled": false,
      "is_minimum_duration_enabled": false,
      "metric_groups": [],
      "subject_type_id": "c2b3d4e5-0000-0000-0000-000000000000"
    },
    "type": "protocols"
  }
}
EOF