--- title: Create experiment protocol description: Datadog, the leading service for cloud-scale monitoring. breadcrumbs: Docs > API Reference > Experiments --- > For the complete documentation index, see [llms.txt](https://docs.datadoghq.com/llms.txt). {% callout %} # Important note for users on the following Datadog sites: app.ddog-gov.com, us2.ddog-gov.com {% alert level="danger" %} This product is not supported for your selected [Datadog site](https://docs.datadoghq.com/getting_started/site.md). ({% placeholder "user-datadog-site-name" /%}). {% /alert %} {% /callout %} # Create experiment protocol{% #create-experiment-protocol %} {% tab title="v2" %} | Datadog site | API endpoint | | ----------------- | --------------------------------------------------------------- | | ap1.datadoghq.com | POST https://api.ap1.datadoghq.com/api/v2/experiments/protocols | | ap2.datadoghq.com | POST https://api.ap2.datadoghq.com/api/v2/experiments/protocols | | app.datadoghq.eu | POST https://api.datadoghq.eu/api/v2/experiments/protocols | | app.ddog-gov.com | POST https://api.ddog-gov.com/api/v2/experiments/protocols | | us2.ddog-gov.com | POST https://api.us2.ddog-gov.com/api/v2/experiments/protocols | | uk1.datadoghq.com | POST https://api.uk1.datadoghq.com/api/v2/experiments/protocols | | app.datadoghq.com | POST https://api.datadoghq.com/api/v2/experiments/protocols | | us3.datadoghq.com | POST https://api.us3.datadoghq.com/api/v2/experiments/protocols | | us5.datadoghq.com | POST https://api.us5.datadoghq.com/api/v2/experiments/protocols | ### Overview Create a draft protocol with a name and optional description and migration metadata. The organization's default subject type is selected. Use PATCH to configure the draft, then publish it before creating experiments from it. This endpoint requires the `product_analytics_experiments_write` permission. OAuth apps require the `product_analytics_experiments_write` authorization [scope](https://docs.datadoghq.com/api/latest/scopes.md#experiments) to access this endpoint. ### Request #### Body Data (required) {% tab title="Model" %} | Parent field | Field | Type | Description | | ------------ | ---------------------------- | ------ | -------------------------------------------------------------------------------------------------------------------- | | | data [*required*] | object | JSON:API protocol request resource. | | data | attributes [*required*] | object | Create a draft protocol with the organization default subject type. | | attributes | description | string | Optional text that explains the protocol. | | attributes | migration_metadata | object | Metadata for imported resources. Must encode to at most 4096 bytes. Null clears it; omission preserves it on update. | | attributes | name [*required*] | string | Protocol name. Leading and trailing spaces are removed. The trimmed name must contain 1 to 255 characters. | | data | type [*required*] | enum | Protocols resource type. Allowed enum values: `protocols` | {% /tab %} {% tab title="Example" %} ```json { "data": { "type": "protocols", "attributes": { "name": "ex-protocol-14bb9543f523edde", "description": "Protocol created by the API test." } } } ``` {% /tab %} ### Response {% tab title="201" %} Created {% tab title="Model" %} Response containing the protocol. | Parent field | Field | Type | Description | | ------------------------------------ | ----------------------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | data [*required*] | object | JSON:API resource containing the protocol identity and fields. | | data | attributes | object | Settings and defaults supplied by the protocol. | | attributes | analysis_plan | object | Default statistical settings supplied by the protocol. | | analysis_plan | compute_cuped | boolean | Whether to use pre-experiment data to reduce variance with CUPED. | | analysis_plan | confidence_interval_method | string | Statistical method used to calculate confidence intervals. | | analysis_plan | confidence_level | double | Confidence level used by the statistical analysis. | | analysis_plan | multiple_testing_correction_method | string | Method used to adjust for testing multiple metrics. | | attributes | archived_at | date-time | Time when the protocol was archived. Omitted if it has not been archived. | | attributes | assignment_source_default_properties | [object] | Default properties supplied by the protocol's assignment source. | | assignment_source_default_properties | column_name | string | Source column that supplies this assignment property. | | assignment_source_default_properties | column_type | string | Data type of the source column. | | assignment_source_default_properties | name | string | Display name of the assignment source property. | | attributes | assignment_source_id | string | ID of the assignment source selected by the protocol. | | attributes | created_at [*required*] | date-time | Time when the protocol was created. | | attributes | default_duration_days | int64 | Default experiment duration supplied by the protocol, in days. | | attributes | description | string | Text that explains the protocol. | | attributes | enforcement | object | Controls that determine which protocol settings can be changed in an experiment. | | enforcement | confidence_interval_method | string | Always LOCKED. The server keeps this setting locked regardless of the supplied value. | | enforcement | confidence_level | string | LOCKED prevents changes to confidence level. EDITABLE permits changes. | | enforcement | cuped_calculation | string | LOCKED prevents changes to CUPED variance reduction. EDITABLE permits changes. | | enforcement | default_duration | string | LOCKED prevents changes to default duration. EDITABLE permits changes. | | enforcement | environment | string | LOCKED prevents changes to environment. EDITABLE permits changes. | | enforcement | flag_source | string | Always LOCKED. The server keeps this setting locked regardless of the supplied value. | | enforcement | multiple_testing_correction | string | LOCKED prevents changes to multiple testing correction. EDITABLE permits changes. | | enforcement | notifications | string | LOCKED prevents changes to notifications. EDITABLE permits changes. | | enforcement | primary_metric | string | LOCKED prevents changes to primary metric. EDITABLE permits changes. | | enforcement | secondary_metrics | string | LOCKED prevents changes to secondary metrics. EDITABLE permits changes. | | enforcement | split_by_exploration_dimensions | string | LOCKED prevents changes to result exploration dimensions. EDITABLE permits changes. | | enforcement | subject_type | string | Always LOCKED. The server keeps this setting locked regardless of the supplied value. | | enforcement | targeting_rules | string | LOCKED prevents changes to targeting rules. EDITABLE permits changes. | | enforcement | traffic_exposure | string | LOCKED prevents changes to traffic exposure. EDITABLE permits changes. | | enforcement | warehouse_exposure_source | string | LOCKED prevents changes to warehouse exposure source. EDITABLE permits changes. | | attributes | environment_id | string | ID of the feature flag environment used by the experiment. | | attributes | 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. | | attributes | exposure_schedule | object | Schedule that controls traffic exposure for experiments created from the protocol. | | exposure_schedule | autostart | boolean | Whether the exposure schedule starts automatically. | | exposure_schedule | guardrail_triggered_action | string | Action taken when a guardrail triggers during the exposure schedule. | | exposure_schedule | rollout_steps | [object] | Ordered steps that define changes in traffic exposure. | | rollout_steps | exposure_ratio | double | Fraction of traffic exposed during this rollout step. | | rollout_steps | grouped_step_index | int64 | Index of the group that contains this rollout step. | | rollout_steps | interval_ms | int64 | Duration of this rollout step, in milliseconds. | | rollout_steps | is_pause_record | boolean | Whether this schedule entry represents a pause. | | rollout_steps | order_position | int64 | Position of this entry in the ordered configuration. | | exposure_schedule | selection_interval_ms | int64 | Interval between traffic selections, in milliseconds. | | exposure_schedule | strategy | string | Method used to increase traffic exposure over the schedule. | | attributes | is_duration_required_to_start [*required*] | boolean | Whether the protocol requires a duration before an experiment can start. | | attributes | is_equal_split_enforced [*required*] | boolean | Whether the protocol requires equal traffic allocation across variants. | | attributes | is_metric_limit_enabled [*required*] | boolean | Whether the protocol limits the number of metrics. | | attributes | is_minimum_duration_enabled [*required*] | boolean | Whether the protocol enforces a minimum experiment duration. | | attributes | metric_groups [*required*] | [object] | Metric groups supplied by the protocol. | | metric_groups | is_decision | boolean | Whether the group contains decision metrics. | | metric_groups | metrics | [object] | Metrics included in this group. | | metrics | metric_id [*required*] | uuid | Identifier of the metric to include in the collection. | | metric_groups | name | string | Display name of the metric group. | | attributes | metric_limit | int64 | Maximum number of metrics allowed by the protocol. | | attributes | migration_metadata | | Metadata retained for resources imported from another system. | | attributes | minimum_duration_unit | string | Unit used to express the protocol's minimum duration. | | attributes | minimum_duration_value | int64 | Minimum experiment duration in the specified unit. | | attributes | name [*required*] | string | Display name of the protocol. | | attributes | primary_metric | object | Subject type selected by the protocol. | | primary_metric | id | string | ID of the subject type. | | primary_metric | name | string | Display name of the subject type. | | attributes | primary_metric_id | string | ID of the primary metric supplied by the protocol. | | attributes | published_at | date-time | Time when the protocol was published. | | attributes | status [*required*] | enum | Publication status of the protocol. Allowed enum values: `DRAFT,PUBLISHED,ARCHIVED` | | attributes | subject_type | object | Subject type selected by the protocol. | | subject_type | id | string | ID of the subject type. | | subject_type | name | string | Display name of the subject type. | | attributes | subject_type_id | string | ID of the subject type used by this configuration. | | attributes | targeting_rules | [object] | Rules that select subjects for the experiment. | | targeting_rules | conditions | [object] | Conditions that define this targeting rule. | | conditions | attribute | string | Subject attribute evaluated by the targeting condition. | | conditions | operator | string | Comparison applied to the subject attribute. | | conditions | order_position | int64 | Position of this entry in the ordered configuration. | | conditions | saved_filter_id | string | ID of the saved filter used by this targeting condition. | | conditions | value | [string] | Values compared with the subject attribute in this condition. | | attributes | updated_at [*required*] | string | RFC3339 update time. Preserve all fractional seconds when passing this value as `expected_updated_at`. | | data | id [*required*] | uuid | ID of the protocol. | | data | type [*required*] | enum | Protocols resource type. Allowed enum values: `protocols` | {% /tab %} {% tab title="Example" %} ```json { "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" } } ``` {% /tab %} {% /tab %} {% tab title="400" %} Invalid request or protocol settings. {% tab title="Model" %} API error response. | Parent field | Field | Type | Description | | ------------ | ------------------------ | -------- | ------------------------------------------------------------------------------- | | | errors [*required*] | [object] | A list of errors. | | errors | detail | string | A human-readable explanation specific to this occurrence of the error. | | errors | meta | object | Non-standard meta-information about the error | | errors | source | object | References to the source of the error. | | source | header | string | A string indicating the name of a single request header which caused the error. | | source | parameter | string | A string indicating which URI query parameter caused the error. | | source | pointer | string | A JSON pointer to the value in the request document that caused the error. | | errors | status | string | Status code of the response. | | errors | title | string | Short human-readable summary of the error. | {% /tab %} {% tab title="Example" %} ```json { "errors": [ { "detail": "Missing required attribute in body", "meta": {}, "source": { "header": "Authorization", "parameter": "limit", "pointer": "/data/attributes/title" }, "status": "400", "title": "Bad Request" } ] } ``` {% /tab %} {% /tab %} {% tab title="401" %} Missing or invalid authentication. {% tab title="Model" %} API error response. | Parent field | Field | Type | Description | | ------------ | ------------------------ | -------- | ------------------------------------------------------------------------------- | | | errors [*required*] | [object] | A list of errors. | | errors | detail | string | A human-readable explanation specific to this occurrence of the error. | | errors | meta | object | Non-standard meta-information about the error | | errors | source | object | References to the source of the error. | | source | header | string | A string indicating the name of a single request header which caused the error. | | source | parameter | string | A string indicating which URI query parameter caused the error. | | source | pointer | string | A JSON pointer to the value in the request document that caused the error. | | errors | status | string | Status code of the response. | | errors | title | string | Short human-readable summary of the error. | {% /tab %} {% tab title="Example" %} ```json { "errors": [ { "detail": "Missing required attribute in body", "meta": {}, "source": { "header": "Authorization", "parameter": "limit", "pointer": "/data/attributes/title" }, "status": "400", "title": "Bad Request" } ] } ``` {% /tab %} {% /tab %} {% tab title="403" %} The caller lacks the product_analytics_experiments_write permission. {% tab title="Model" %} API error response. | Parent field | Field | Type | Description | | ------------ | ------------------------ | -------- | ------------------------------------------------------------------------------- | | | errors [*required*] | [object] | A list of errors. | | errors | detail | string | A human-readable explanation specific to this occurrence of the error. | | errors | meta | object | Non-standard meta-information about the error | | errors | source | object | References to the source of the error. | | source | header | string | A string indicating the name of a single request header which caused the error. | | source | parameter | string | A string indicating which URI query parameter caused the error. | | source | pointer | string | A JSON pointer to the value in the request document that caused the error. | | errors | status | string | Status code of the response. | | errors | title | string | Short human-readable summary of the error. | {% /tab %} {% tab title="Example" %} ```json { "errors": [ { "detail": "Missing required attribute in body", "meta": {}, "source": { "header": "Authorization", "parameter": "limit", "pointer": "/data/attributes/title" }, "status": "400", "title": "Bad Request" } ] } ``` {% /tab %} {% /tab %} {% tab title="409" %} A protocol with this name already exists. {% tab title="Model" %} API error response. | Parent field | Field | Type | Description | | ------------ | ------------------------ | -------- | ------------------------------------------------------------------------------- | | | errors [*required*] | [object] | A list of errors. | | errors | detail | string | A human-readable explanation specific to this occurrence of the error. | | errors | meta | object | Non-standard meta-information about the error | | errors | source | object | References to the source of the error. | | source | header | string | A string indicating the name of a single request header which caused the error. | | source | parameter | string | A string indicating which URI query parameter caused the error. | | source | pointer | string | A JSON pointer to the value in the request document that caused the error. | | errors | status | string | Status code of the response. | | errors | title | string | Short human-readable summary of the error. | {% /tab %} {% tab title="Example" %} ```json { "errors": [ { "detail": "Missing required attribute in body", "meta": {}, "source": { "header": "Authorization", "parameter": "limit", "pointer": "/data/attributes/title" }, "status": "400", "title": "Bad Request" } ] } ``` {% /tab %} {% /tab %} {% tab title="415" %} Unsupported request content type. {% tab title="Model" %} API error response. | Parent field | Field | Type | Description | | ------------ | ------------------------ | -------- | ------------------------------------------------------------------------------- | | | errors [*required*] | [object] | A list of errors. | | errors | detail | string | A human-readable explanation specific to this occurrence of the error. | | errors | meta | object | Non-standard meta-information about the error | | errors | source | object | References to the source of the error. | | source | header | string | A string indicating the name of a single request header which caused the error. | | source | parameter | string | A string indicating which URI query parameter caused the error. | | source | pointer | string | A JSON pointer to the value in the request document that caused the error. | | errors | status | string | Status code of the response. | | errors | title | string | Short human-readable summary of the error. | {% /tab %} {% tab title="Example" %} ```json { "errors": [ { "detail": "Missing required attribute in body", "meta": {}, "source": { "header": "Authorization", "parameter": "limit", "pointer": "/data/attributes/title" }, "status": "400", "title": "Bad Request" } ] } ``` {% /tab %} {% /tab %} {% tab title="429" %} Too many requests {% tab title="Model" %} API error response. | Field | Type | Description | | ------------------------ | -------- | ----------------- | | errors [*required*] | [string] | A list of errors. | {% /tab %} {% tab title="Example" %} ```json { "errors": [ "Bad Request" ] } ``` {% /tab %} {% /tab %} {% tab title="500" %} Internal Server Error {% tab title="Model" %} API error response. | Parent field | Field | Type | Description | | ------------ | ------------------------ | -------- | ------------------------------------------------------------------------------- | | | errors [*required*] | [object] | A list of errors. | | errors | detail | string | A human-readable explanation specific to this occurrence of the error. | | errors | meta | object | Non-standard meta-information about the error | | errors | source | object | References to the source of the error. | | source | header | string | A string indicating the name of a single request header which caused the error. | | source | parameter | string | A string indicating which URI query parameter caused the error. | | source | pointer | string | A JSON pointer to the value in the request document that caused the error. | | errors | status | string | Status code of the response. | | errors | title | string | Short human-readable summary of the error. | {% /tab %} {% tab title="Example" %} ```json { "errors": [ { "detail": "Missing required attribute in body", "meta": {}, "source": { "header": "Authorization", "parameter": "limit", "pointer": "/data/attributes/title" }, "status": "400", "title": "Bad Request" } ] } ``` {% /tab %} {% /tab %} ### Code Example ##### \## default # \# Use a Personal Access Token or Service Access Token export DD_BEARER_TOKEN="" \# Curl command curl -X POST "https://api.datadoghq.com/api/v2/experiments/protocols" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer ${DD_BEARER_TOKEN}" \ -d @- << EOF { "data": { "attributes": { "description": "Defaults for checkout experiments.", "name": "Checkout protocol" }, "type": "protocols" } } EOF {% /tab %}