--- title: "Replace experiment protocol" method: PUT path: "/api/v2/experiments/protocols/{protocol_id}" tags: ["Experiments"] --- # Replace experiment protocol `PUT /api/v2/experiments/protocols/{protocol_id}` ## Request - Base URL: `https://api.datadoghq.com` - URL: `https://api.datadoghq.com/api/v2/experiments/protocols/{protocol_id}` - Auth: one of: - API key in header `DD-API-KEY` and API key in header `DD-APPLICATION-KEY` - OAuth 2 - Authorization code: `/oauth2/v1/authorize` - Token URL: `/oauth2/v1/token` scopes: `product_analytics_experiments_write` - TypeScript: (a function with typed inputs; its response is checked against the schema) 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. ## Path parameters - `protocol_id` string, uuid, required: The UUID of the protocol. ## Query parameters - `expected_updated_at` string ## Request body - ExperimentsReplaceExperimentProtocolRequest: Replace a published protocol template. Omitted optional template fields are cleared. Omitted enforcement and migration_metadata are preserved. Enabled limits require their values; allocation settings require environment_id. - `data` ExperimentsReplaceExperimentProtocolRequestData, required: JSON:API protocol request resource. - `attributes` ExperimentsReplaceExperimentProtocolRequestDataAttributes, required: Replace a published protocol template. Omitted optional template fields are cleared. Omitted enforcement and migration_metadata are preserved. Enabled limits require their values; allocation settings require environment_id. - `analysis_plan` ExperimentsProtocolAnalysisPlanInput, nullable: Statistical settings. Use `default_duration_days` for duration; `target_duration_days` is not accepted here. - `compute_cuped` boolean, nullable: Whether to use pre-experiment data to reduce variance with CUPED. - `confidence_interval_method` string: Confidence interval method: `Sequential`, `FixedSample`, `Bayesian`, or `SequentialFixedHybrid`. An empty string leaves the method unset. - `confidence_level` number, double, nullable: Confidence level used by the statistical analysis. - `multiple_testing_correction_method` string, nullable: Method used to adjust for testing multiple metrics. - `assignment_source_default_properties` ExperimentsPublicProtocolResponseDataAttributesAssignmentSourceDefaultPropertiesItems[]: Assignment properties. - `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, uuid, nullable: ID of the assignment source selected by the protocol. - `default_duration_days` integer, nullable: Default experiment duration supplied by the protocol, in days. - `enforcement` ExperimentsReplaceProtocolEnforcementInput: Complete lock map. Omit this object to preserve current locks. Null is rejected; every field is required. - `confidence_interval_method` string, required: Always LOCKED. The server keeps this setting locked regardless of the supplied value. - `confidence_level` string, required: LOCKED prevents changes to confidence level. EDITABLE permits changes. - `cuped_calculation` string, required: LOCKED prevents changes to CUPED variance reduction. EDITABLE permits changes. - `default_duration` string, required: LOCKED prevents changes to default duration. EDITABLE permits changes. - `environment` string, required: LOCKED prevents changes to environment. EDITABLE permits changes. - `flag_source` string, required: Always LOCKED. The server keeps this setting locked regardless of the supplied value. - `multiple_testing_correction` string, required: LOCKED prevents changes to multiple testing correction. EDITABLE permits changes. - `notifications` string, required: LOCKED prevents changes to notifications. EDITABLE permits changes. - `primary_metric` string, required: LOCKED prevents changes to primary metric. EDITABLE permits changes. - `secondary_metrics` string, required: LOCKED prevents changes to secondary metrics. EDITABLE permits changes. - `split_by_exploration_dimensions` string, required: LOCKED prevents changes to result exploration dimensions. EDITABLE permits changes. - `subject_type` string, required: Always LOCKED. The server keeps this setting locked regardless of the supplied value. - `targeting_rules` string, required: LOCKED prevents changes to targeting rules. EDITABLE permits changes. - `traffic_exposure` string, required: LOCKED prevents changes to traffic exposure. EDITABLE permits changes. - `warehouse_exposure_source` string, required: LOCKED prevents changes to warehouse exposure source. EDITABLE permits changes. - `environment_id` string, uuid, nullable: ID of the feature flag environment used by the experiment. - `exposure_schedule` ExperimentsProtocolExposureScheduleInput, nullable: Traffic schedule. Publishing and replacement require `NO_ROLLOUT` with exactly one step, or `UNIFORM_INTERVALS` with a positive selection interval and at least one step. Requires `environment_id`. - `autostart` boolean: Whether the exposure schedule starts automatically. - `guardrail_triggered_action` string, nullable: Action taken when a guardrail triggers during the exposure schedule. - `rollout_steps` ExperimentsProtocolExposureStepInput[], nullable: Rollout steps, replaced when supplied. - `exposure_ratio` number, double: Fraction of traffic exposed during this rollout step. - `grouped_step_index` integer, nullable: Index of the group that contains this rollout step. - `interval_ms` integer, nullable: Duration of this rollout step, in milliseconds. - `is_pause_record` boolean: Whether this schedule entry represents a pause. - `order_position` integer: Position of this entry in the ordered configuration. - `selection_interval_ms` integer, nullable: Interval between traffic selections, in milliseconds. - `strategy` string: Method used to increase traffic exposure over the schedule. - `is_duration_required_to_start` boolean, required: Whether the protocol requires a duration before an experiment can start. - `is_equal_split_enforced` boolean, required: Whether the protocol requires equal traffic allocation across variants. - `is_metric_limit_enabled` boolean, required: Whether the protocol limits the number of metrics. - `is_minimum_duration_enabled` boolean, required: Whether the protocol enforces a minimum experiment duration. - `metric_groups` ExperimentsProtocolMetricGroupInput[], required: Metric groups. - `is_decision` boolean: Whether this group contains decision metrics. - `metrics` ExperimentsProtocolMetricInput[], nullable: Metrics in the group. - `metric_id` string, uuid, required: Metric UUID. - `name` string: Metric group name. - `metric_limit` integer, nullable: Maximum number of metrics allowed by the protocol. - `migration_metadata` object, nullable: Metadata for imported resources. Must encode to at most 4096 bytes. Null clears it; omission preserves it on update. - `minimum_duration_unit` string, nullable: Minimum duration unit, DAYS or WEEKS. - `minimum_duration_value` integer, nullable: Minimum experiment duration in the specified unit. - `primary_metric_id` string, uuid, nullable: ID of the primary metric supplied by the protocol. - `subject_type_id` string, uuid, required: ID of the subject type used by this configuration. - `targeting_rules` ExperimentsProtocolTargetingRuleInput[]: Targeting rules. - `conditions` ExperimentsProtocolConditionInput[], nullable: Conditions in this rule. - `attribute` string: Subject attribute evaluated by the targeting condition. - `operator` string: Comparison applied to the subject attribute. - `order_position` integer: Position of this entry in the ordered configuration. - `saved_filter_id` string, nullable: Saved filter UUID. Null selects an inline condition. An empty string skips the saved-filter lookup. - `value` string[], nullable: Values compared with the subject attribute in this condition. - `id` string, uuid: Protocol ID. If supplied, must match the path protocol_id. - `type` 'protocols', required: Protocols resource type. ## Response `200` OK - ExperimentsPublicProtocolResponse: Response containing the protocol. - `data` ExperimentsPublicProtocolResponseData, required: JSON:API resource containing the protocol identity and fields. - `attributes` ExperimentsPublicProtocolResponseDataAttributes: Settings and defaults supplied by the protocol. - `analysis_plan` ExperimentsPublicProtocolResponseDataAttributesAnalysisPlan: 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` number, double: Confidence level used by the statistical analysis. - `multiple_testing_correction_method` string: Method used to adjust for testing multiple metrics. - `archived_at` string, date-time: Time when the protocol was archived. Omitted if it has not been archived. - `assignment_source_default_properties` ExperimentsPublicProtocolResponseDataAttributesAssignmentSourceDefaultPropertiesItems[]: 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` string, date-time, required: Time when the protocol was created. - `default_duration_days` integer: Default experiment duration supplied by the protocol, in days. - `description` string: Text that explains the protocol. - `enforcement` ExperimentsPublicProtocolResponseDataAttributesEnforcement: 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` integer: 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` ExperimentsPublicProtocolResponseDataAttributesExposureSchedule: 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` ExperimentsPublicProtocolResponseDataAttributesExposureScheduleRolloutStepsItems[]: Ordered steps that define changes in traffic exposure. - `exposure_ratio` number, double: Fraction of traffic exposed during this rollout step. - `grouped_step_index` integer: Index of the group that contains this rollout step. - `interval_ms` integer: Duration of this rollout step, in milliseconds. - `is_pause_record` boolean: Whether this schedule entry represents a pause. - `order_position` integer: Position of this entry in the ordered configuration. - `selection_interval_ms` integer: Interval between traffic selections, in milliseconds. - `strategy` string: Method used to increase traffic exposure over the schedule. - `is_duration_required_to_start` boolean, required: Whether the protocol requires a duration before an experiment can start. - `is_equal_split_enforced` boolean, required: Whether the protocol requires equal traffic allocation across variants. - `is_metric_limit_enabled` boolean, required: Whether the protocol limits the number of metrics. - `is_minimum_duration_enabled` boolean, required: Whether the protocol enforces a minimum experiment duration. - `metric_groups` ExperimentsPublicProtocolResponseDataAttributesMetricGroupsItems[], required: Metric groups supplied by the protocol. - `is_decision` boolean: Whether the group contains decision metrics. - `metrics` ExperimentsCreateMetricCollectionV2RequestDataAttributesMetricsItems[]: Metrics included in this group. - `metric_id` string, uuid, required: Identifier of the metric to include in the collection. - `name` string: Display name of the metric group. - `metric_limit` integer: Maximum number of metrics allowed by the protocol. - `migration_metadata` unknown - `minimum_duration_unit` string: Unit used to express the protocol's minimum duration. - `minimum_duration_value` integer: Minimum experiment duration in the specified unit. - `name` string, required: Display name of the protocol. - `primary_metric` ExperimentsPublicProtocolResponseDataAttributesSubjectType: 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` string, date-time: Time when the protocol was published. - `status` 'DRAFT' | 'PUBLISHED' | 'ARCHIVED', required: Publication status of the protocol. - `subject_type` ExperimentsPublicProtocolResponseDataAttributesSubjectType: 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` ExperimentsPublicProtocolResponseDataAttributesTargetingRulesItems[]: Rules that select subjects for the experiment. - `conditions` ExperimentsPublicProtocolResponseDataAttributesTargetingRulesItemsConditionsItems[]: 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` integer: 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` string, required: RFC3339 update time. Preserve all fractional seconds when passing this value as `expected_updated_at`. - `id` string, uuid, required: ID of the protocol. - `type` 'protocols', required: Protocols resource type. ## Other responses - `400`: Invalid request or protocol settings. - `401`: Missing or invalid authentication. - `403`: The caller lacks the product_analytics_experiments_write permission. - `404`: No protocol with this ID exists in the organization. - `409`: The protocol is not published or expected_updated_at is stale. - `415`: Unsupported request content type. - `429`: Too many requests - `500`: Internal Server Error --- [API](https://skmtc.dev/datadog/apis/datadog-api-v2-collection.md) - [All operations](https://skmtc.dev/datadog/apis/datadog-api-v2-collection/llms.txt) - [OpenAPI document](https://skmtc.dev/datadog/apis/datadog-api-v2-collection/revisions/3f70db624329?raw)