--- title: "Create experiment protocol" method: POST path: "/api/v2/experiments/protocols" tags: ["Experiments"] --- # Create experiment protocol `POST /api/v2/experiments/protocols` ## Request - Base URL: `https://api.datadoghq.com` - URL: `https://api.datadoghq.com/api/v2/experiments/protocols` - 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) 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. ## Request body - ExperimentsCreateExperimentProtocolRequest: Create a draft protocol with the organization default subject type. - `data` ExperimentsCreateExperimentProtocolRequestData, required: JSON:API protocol request resource. - `attributes` ExperimentsCreateExperimentProtocolRequestDataAttributes, required: Create a draft protocol with the organization default subject type. - `description` string, nullable: Optional text that explains 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. - `name` string, required: Protocol name. Leading and trailing spaces are removed. The trimmed name must contain 1 to 255 characters. - `type` 'protocols', required: Protocols resource type. ## Response `201` Created - 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. - `409`: A protocol with this name already exists. - `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)