--- title: "Create metric" method: POST path: "/api/v2/experiments/metrics" tags: ["Experiments"] --- # Create metric `POST /api/v2/experiments/metrics` ## Request - Base URL: `https://api.datadoghq.com` - URL: `https://api.datadoghq.com/api/v2/experiments/metrics` - 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_metrics_write` - TypeScript: (a function with typed inputs; its response is checked against the schema) Create a metric. The metric's type is derived from the aggregation shape: a numerator alone is SIMPLE, a numerator with a denominator is RATIO, and a percentile aggregation is PERCENTILE. Warehouse aggregations reference measures by UUID. Property filters use property_id or measure_id UUIDs returned by the same metric SQL model; every reference must belong to the aggregation's data source. The is_certified attribute is rejected. Certification cannot be changed through this endpoint. ## Request body - ExperimentsCreateMetricV2Request: Request to create an experiment metric. - `data` ExperimentsCreateMetricV2RequestData, required: Metric resource to create. - `attributes` union, required: Configuration for the new metric. Supply either numerator_aggregation or percentile_aggregation. A denominator_aggregation requires numerator_aggregation. Omit unused aggregation fields; do not send them as null. - ExperimentsCreateMetricNumeratorAttributes: Configuration for a metric calculated from a numerator and an optional denominator. Omit percentile_aggregation. Omit denominator_aggregation when unused. - `data_source_type` 'DATADOG' | 'DATADOG_REFERENCE_TABLE' | 'CUSTOMER_WAREHOUSE', required: Source of the data backing this metric. - `denominator_aggregation` union: Measure and calculation settings for a numerator or denominator aggregation. Supply exactly one non-null measure. - ExperimentsWarehouseMetricAggregationInput: Settings for a metric aggregation that uses a Warehouse measure. The other measure must be omitted or null. - `aging_threshold_days` integer: Stored aging threshold in days. The subject aging filter uses the aggregation window end and unit. - `datadog_metric_measure` ExperimentsNullableDatadogMetricMeasureInput, nullable: Optional Datadog measure. Use null when the other measure is selected. - … - `enable_aging_subject_filter` boolean: Whether to exclude subjects whose observation time is shorter than the aggregation window. - `operation` string, required: Calculation applied to the measure values, such as sum. - `property_filters` ExperimentsWarehouseFilterInputGroup[], nullable: Property filters that select data for this aggregation. - … - `threshold_aggregation_type` string: Calculation used to evaluate the threshold. - `threshold_breach_value` number, double: Value used to determine whether the threshold is breached. - `threshold_comparison_operator` string: Operator used to compare the calculated value with the threshold. - `threshold_timeframe_dimension` string: Time unit for the threshold evaluation window. Supports seconds, minutes, hours, days, calendar_days, and weeks. Calendar days start at midnight on the assignment day. Other units start at the assignment time. - `threshold_timeframe_value` number, double: End of the threshold evaluation window, measured from assignment in the configured time unit. - `timeframe_end_value` number, double: End offset of the aggregation window from assignment, in timeframe_unit. - `timeframe_start_value` number, double: Start offset of the aggregation window from assignment, in timeframe_unit. - `timeframe_unit` string: Time unit for the aggregation window. Calendar days are measured from midnight on the assignment day. Other units are measured from the assignment time. - `warehouse_metric_measure` ExperimentsWarehouseMetricMeasure, required: Reference to a measure defined in a warehouse metric SQL model. - … - `winsor_lower_fixed_value` number, double: Fixed lower bound used to cap extreme measure values. - `winsor_lower_percentile` number, double: Percentile used to determine the lower bound for extreme measure values. - `winsor_upper_fixed_value` number, double: Fixed upper bound used to cap extreme measure values. - `winsor_upper_percentile` number, double: Percentile used to determine the upper bound for extreme measure values. - `winsorization_strategy` string: Method used to cap extreme measure values before aggregation. - ExperimentsDatadogMetricAggregationInput: Settings for a metric aggregation that uses a Datadog measure. The other measure must be omitted or null. - `aging_threshold_days` integer: Stored aging threshold in days. The subject aging filter uses the aggregation window end and unit. - `datadog_metric_measure` ExperimentsDatadogMetricMeasureInput, required: Datadog source and query that supply values for the metric. - … - `enable_aging_subject_filter` boolean: Whether to exclude subjects whose observation time is shorter than the aggregation window. - `operation` string, required: Calculation applied to the measure values, such as sum. - `property_filters` ExperimentsPropertyFilterInputGroup[], nullable: Property filters that select data for this aggregation. - … - `threshold_aggregation_type` string: Calculation used to evaluate the threshold. - `threshold_breach_value` number, double: Value used to determine whether the threshold is breached. - `threshold_comparison_operator` string: Operator used to compare the calculated value with the threshold. - `threshold_timeframe_dimension` string: Time unit for the threshold evaluation window. Supports seconds, minutes, hours, days, calendar_days, and weeks. Calendar days start at midnight on the assignment day. Other units start at the assignment time. - `threshold_timeframe_value` number, double: End of the threshold evaluation window, measured from assignment in the configured time unit. - `timeframe_end_value` number, double: End offset of the aggregation window from assignment, in timeframe_unit. - `timeframe_start_value` number, double: Start offset of the aggregation window from assignment, in timeframe_unit. - `timeframe_unit` string: Time unit for the aggregation window. Calendar days are measured from midnight on the assignment day. Other units are measured from the assignment time. - `warehouse_metric_measure` ExperimentsNullableWarehouseMetricMeasureInput, nullable: Optional warehouse measure. Use null when the other measure is selected. - … - `winsor_lower_fixed_value` number, double: Fixed lower bound used to cap extreme measure values. - `winsor_lower_percentile` number, double: Percentile used to determine the lower bound for extreme measure values. - `winsor_upper_fixed_value` number, double: Fixed upper bound used to cap extreme measure values. - `winsor_upper_percentile` number, double: Percentile used to determine the upper bound for extreme measure values. - `winsorization_strategy` string: Method used to cap extreme measure values before aggregation. - `description` string, nullable: Description of the metric. Send null to leave it unset. - `desired_change` 'METRIC_INCREASES' | 'METRIC_DECREASES', required: Direction of change that represents an improvement for this metric. - `format_as_percent` boolean: Whether results render as a percentage. Defaults to false when omitted. - `guardrail_cutoff_threshold` number, double, nullable: Guardrail cutoff threshold. Send null to leave it unset. - `migration_metadata` unknown - `name` string, required: Name of the metric. - `numerator_aggregation` union, required: Measure and calculation settings for a numerator or denominator aggregation. Supply exactly one non-null measure. - ExperimentsWarehouseMetricAggregationInput: Settings for a metric aggregation that uses a Warehouse measure. The other measure must be omitted or null. - `aging_threshold_days` integer: Stored aging threshold in days. The subject aging filter uses the aggregation window end and unit. - `datadog_metric_measure` ExperimentsNullableDatadogMetricMeasureInput, nullable: Optional Datadog measure. Use null when the other measure is selected. - … - `enable_aging_subject_filter` boolean: Whether to exclude subjects whose observation time is shorter than the aggregation window. - `operation` string, required: Calculation applied to the measure values, such as sum. - `property_filters` ExperimentsWarehouseFilterInputGroup[], nullable: Property filters that select data for this aggregation. - … - `threshold_aggregation_type` string: Calculation used to evaluate the threshold. - `threshold_breach_value` number, double: Value used to determine whether the threshold is breached. - `threshold_comparison_operator` string: Operator used to compare the calculated value with the threshold. - `threshold_timeframe_dimension` string: Time unit for the threshold evaluation window. Supports seconds, minutes, hours, days, calendar_days, and weeks. Calendar days start at midnight on the assignment day. Other units start at the assignment time. - `threshold_timeframe_value` number, double: End of the threshold evaluation window, measured from assignment in the configured time unit. - `timeframe_end_value` number, double: End offset of the aggregation window from assignment, in timeframe_unit. - `timeframe_start_value` number, double: Start offset of the aggregation window from assignment, in timeframe_unit. - `timeframe_unit` string: Time unit for the aggregation window. Calendar days are measured from midnight on the assignment day. Other units are measured from the assignment time. - `warehouse_metric_measure` ExperimentsWarehouseMetricMeasure, required: Reference to a measure defined in a warehouse metric SQL model. - … - `winsor_lower_fixed_value` number, double: Fixed lower bound used to cap extreme measure values. - `winsor_lower_percentile` number, double: Percentile used to determine the lower bound for extreme measure values. - `winsor_upper_fixed_value` number, double: Fixed upper bound used to cap extreme measure values. - `winsor_upper_percentile` number, double: Percentile used to determine the upper bound for extreme measure values. - `winsorization_strategy` string: Method used to cap extreme measure values before aggregation. - ExperimentsDatadogMetricAggregationInput: Settings for a metric aggregation that uses a Datadog measure. The other measure must be omitted or null. - `aging_threshold_days` integer: Stored aging threshold in days. The subject aging filter uses the aggregation window end and unit. - `datadog_metric_measure` ExperimentsDatadogMetricMeasureInput, required: Datadog source and query that supply values for the metric. - … - `enable_aging_subject_filter` boolean: Whether to exclude subjects whose observation time is shorter than the aggregation window. - `operation` string, required: Calculation applied to the measure values, such as sum. - `property_filters` ExperimentsPropertyFilterInputGroup[], nullable: Property filters that select data for this aggregation. - … - `threshold_aggregation_type` string: Calculation used to evaluate the threshold. - `threshold_breach_value` number, double: Value used to determine whether the threshold is breached. - `threshold_comparison_operator` string: Operator used to compare the calculated value with the threshold. - `threshold_timeframe_dimension` string: Time unit for the threshold evaluation window. Supports seconds, minutes, hours, days, calendar_days, and weeks. Calendar days start at midnight on the assignment day. Other units start at the assignment time. - `threshold_timeframe_value` number, double: End of the threshold evaluation window, measured from assignment in the configured time unit. - `timeframe_end_value` number, double: End offset of the aggregation window from assignment, in timeframe_unit. - `timeframe_start_value` number, double: Start offset of the aggregation window from assignment, in timeframe_unit. - `timeframe_unit` string: Time unit for the aggregation window. Calendar days are measured from midnight on the assignment day. Other units are measured from the assignment time. - `warehouse_metric_measure` ExperimentsNullableWarehouseMetricMeasureInput, nullable: Optional warehouse measure. Use null when the other measure is selected. - … - `winsor_lower_fixed_value` number, double: Fixed lower bound used to cap extreme measure values. - `winsor_lower_percentile` number, double: Percentile used to determine the lower bound for extreme measure values. - `winsor_upper_fixed_value` number, double: Fixed upper bound used to cap extreme measure values. - `winsor_upper_percentile` number, double: Percentile used to determine the upper bound for extreme measure values. - `winsorization_strategy` string: Method used to cap extreme measure values before aggregation. - ExperimentsCreateMetricPercentileAttributes: Configuration for a percentile metric. Omit numerator_aggregation and denominator_aggregation. - `data_source_type` 'DATADOG' | 'DATADOG_REFERENCE_TABLE' | 'CUSTOMER_WAREHOUSE', required: Source of the data backing this metric. - `description` string, nullable: Description of the metric. Send null to leave it unset. - `desired_change` 'METRIC_INCREASES' | 'METRIC_DECREASES', required: Direction of change that represents an improvement for this metric. - `format_as_percent` boolean: Whether results render as a percentage. Defaults to false when omitted. - `guardrail_cutoff_threshold` number, double, nullable: Guardrail cutoff threshold. Send null to leave it unset. - `migration_metadata` unknown - `name` string, required: Name of the metric. - `percentile_aggregation` union, required: Measure and percentile to calculate for the metric. Supply exactly one non-null measure. - ExperimentsWarehousePercentileAggregationInput: Settings for a percentile aggregation that uses a Warehouse measure. The other measure must be omitted or null. - `datadog_metric_measure` ExperimentsNullableDatadogPercentileMeasureInput, nullable: Optional Datadog percentile measure. Use null when the warehouse measure is selected. - … - `percentile` number, double, required: Percentile to calculate from the measure values. - `property_filters` ExperimentsPropertyFilterInputGroup[], nullable: Property filters that select data for the percentile calculation. - … - `warehouse_metric_measure` ExperimentsWarehouseMetricMeasure, required: Reference to a measure defined in a warehouse metric SQL model. - … - ExperimentsDatadogPercentileAggregationInput: Settings for a percentile aggregation that uses a Datadog measure. The other measure must be omitted or null. - `datadog_metric_measure` ExperimentsDatadogPercentileMeasureInput, required: Datadog measure used to calculate a percentile. - … - `percentile` number, double, required: Percentile to calculate from the measure values. - `property_filters` ExperimentsPropertyFilterInputGroup[], nullable: Property filters that select data for the percentile calculation. - … - `warehouse_metric_measure` ExperimentsNullableWarehouseMetricMeasureInput, nullable: Optional warehouse measure. Use null when the other measure is selected. - … - `type` 'metrics', required: The metric resource type. ## Response `201` Created - ExperimentsMetricV2DTO: Response containing the metric. - `data` ExperimentsMetricV2DTOData, required: JSON:API resource containing the metric identity and fields. - `attributes` ExperimentsMetricV2DTODataAttributes: Details of the metric. - `certified_at` string, date-time, nullable: Time when this resource was certified. - `created_at` string, date-time: Time when this resource was created. - `data_source_type` 'DATADOG' | 'DATADOG_REFERENCE_TABLE' | 'CUSTOMER_WAREHOUSE' | 'IMPORTED' | 'UNKNOWN': Source of the data used to calculate the metric. - `denominator_aggregation` ExperimentsMetricV2DTODataAttributesNumeratorAggregation, nullable: Source measure and aggregation settings for a metric value. - `aging_threshold_days` integer: Stored aging threshold in days. The subject aging filter uses the aggregation window end and unit. - `datadog_metric_measure` ExperimentsMetricV2DTODataAttributesPercentileAggregationDatadogMetricMeasure: Datadog source and query that supply values for the metric. - `column_name` string: Name of the Datadog event field used by this measure. - `column_type` string: Data type of the source column. - `filters` unknown - `name` string: Display name of the Datadog measure. - `query` string: Query used to retrieve the Datadog measure. - `source_definition_filter` unknown - `source_subtype` string: Subtype of the Datadog data source. - `source_type` string: Type of Datadog data source used for the measure. - `enable_aging_subject_filter` boolean: Whether to exclude subjects whose observation time is shorter than the aggregation window. - `operation` string: Aggregation applied to the selected measure. - `pipeline_column_suffix` string: Suffix used to identify this value in pipeline output columns. - `property_filters` ExperimentsMetricPropertyFilterGroup[]: Filters applied to the metric aggregation. - ExperimentsMetricPropertyFilter[]: Metric property filters combined with AND. - `measure_id` string: ID of the measure evaluated by the filter. - `operation` string: Comparison applied by the filter. - `property_id` string: ID of the property evaluated by the filter. - `values` string[]: Values used by the filter's comparison. - `threshold_aggregation_type` string: Aggregation used to evaluate the threshold. - `threshold_breach_value` number, double: Value used to determine whether the threshold is breached. - `threshold_comparison_operator` string: Comparison applied between the aggregated value and the threshold. - `threshold_timeframe_dimension` string: Time unit used for the threshold evaluation window. - `threshold_timeframe_value` number, double: Size of the threshold evaluation window. - `timeframe_end_value` number, double: End of the aggregation window in the specified time unit. - `timeframe_start_value` number, double: Start of the aggregation window in the specified time unit. - `timeframe_unit` string: Time unit used for the aggregation window. - `warehouse_metric_measure` ExperimentsMetricV2DTODataAttributesPercentileAggregationWarehouseMetricMeasure: Warehouse measure that supplies values for the metric. - `id` string: ID of the measure. - `pipeline_column_suffix` string: Suffix used to identify this value in pipeline output columns. - `winsor_lower_fixed_value` number, double: Fixed lower bound used to cap metric values. - `winsor_lower_percentile` number, double: Percentile used to determine the lower bound for capped metric values. - `winsor_upper_fixed_value` number, double: Fixed upper bound used to cap metric values. - `winsor_upper_percentile` number, double: Percentile used to determine the upper bound for capped metric values. - `winsorization_strategy` string: Method used to cap extreme metric values. - `description` string: Text that explains the metric. - `desired_change` 'METRIC_INCREASES' | 'METRIC_DECREASES' | 'UNKNOWN': Direction of metric change considered desirable. - `experiment_count` integer, nullable: Number of experiments that reference this resource. - `format_as_percent` boolean: Whether to display the metric value as a percentage. - `guardrail_cutoff_threshold` number, double, nullable: Threshold used when evaluating this metric as a guardrail. - `metric_type` 'SIMPLE' | 'RATIO' | 'PERCENTILE' | 'UNKNOWN': Type of metric calculation. - `migration_metadata` unknown - `name` string: Display name of the metric. - `numerator_aggregation` ExperimentsMetricV2DTODataAttributesNumeratorAggregation, nullable: Source measure and aggregation settings for a metric value. - `aging_threshold_days` integer: Stored aging threshold in days. The subject aging filter uses the aggregation window end and unit. - `datadog_metric_measure` ExperimentsMetricV2DTODataAttributesPercentileAggregationDatadogMetricMeasure: Datadog source and query that supply values for the metric. - `column_name` string: Name of the Datadog event field used by this measure. - `column_type` string: Data type of the source column. - `filters` unknown - `name` string: Display name of the Datadog measure. - `query` string: Query used to retrieve the Datadog measure. - `source_definition_filter` unknown - `source_subtype` string: Subtype of the Datadog data source. - `source_type` string: Type of Datadog data source used for the measure. - `enable_aging_subject_filter` boolean: Whether to exclude subjects whose observation time is shorter than the aggregation window. - `operation` string: Aggregation applied to the selected measure. - `pipeline_column_suffix` string: Suffix used to identify this value in pipeline output columns. - `property_filters` ExperimentsMetricPropertyFilterGroup[]: Filters applied to the metric aggregation. - ExperimentsMetricPropertyFilter[]: Metric property filters combined with AND. - `measure_id` string: ID of the measure evaluated by the filter. - `operation` string: Comparison applied by the filter. - `property_id` string: ID of the property evaluated by the filter. - `values` string[]: Values used by the filter's comparison. - `threshold_aggregation_type` string: Aggregation used to evaluate the threshold. - `threshold_breach_value` number, double: Value used to determine whether the threshold is breached. - `threshold_comparison_operator` string: Comparison applied between the aggregated value and the threshold. - `threshold_timeframe_dimension` string: Time unit used for the threshold evaluation window. - `threshold_timeframe_value` number, double: Size of the threshold evaluation window. - `timeframe_end_value` number, double: End of the aggregation window in the specified time unit. - `timeframe_start_value` number, double: Start of the aggregation window in the specified time unit. - `timeframe_unit` string: Time unit used for the aggregation window. - `warehouse_metric_measure` ExperimentsMetricV2DTODataAttributesPercentileAggregationWarehouseMetricMeasure: Warehouse measure that supplies values for the metric. - `id` string: ID of the measure. - `pipeline_column_suffix` string: Suffix used to identify this value in pipeline output columns. - `winsor_lower_fixed_value` number, double: Fixed lower bound used to cap metric values. - `winsor_lower_percentile` number, double: Percentile used to determine the lower bound for capped metric values. - `winsor_upper_fixed_value` number, double: Fixed upper bound used to cap metric values. - `winsor_upper_percentile` number, double: Percentile used to determine the upper bound for capped metric values. - `winsorization_strategy` string: Method used to cap extreme metric values. - `percentile_aggregation` ExperimentsMetricV2DTODataAttributesPercentileAggregation, nullable: Source measure and settings for a percentile metric. - `datadog_metric_measure` ExperimentsMetricV2DTODataAttributesPercentileAggregationDatadogMetricMeasure: Datadog source and query that supply values for the metric. - `column_name` string: Name of the Datadog event field used by this measure. - `column_type` string: Data type of the source column. - `filters` unknown - `name` string: Display name of the Datadog measure. - `query` string: Query used to retrieve the Datadog measure. - `source_definition_filter` unknown - `source_subtype` string: Subtype of the Datadog data source. - `source_type` string: Type of Datadog data source used for the measure. - `percentile` number, double: Percentile calculated from the selected measure. - `pipeline_column_suffix` string: Suffix used to identify this value in pipeline output columns. - `property_filters` ExperimentsMetricPropertyFilterGroup[]: Filters applied to the metric aggregation. - ExperimentsMetricPropertyFilter[]: Metric property filters combined with AND. - `measure_id` string: ID of the measure evaluated by the filter. - `operation` string: Comparison applied by the filter. - `property_id` string: ID of the property evaluated by the filter. - `values` string[]: Values used by the filter's comparison. - `warehouse_metric_measure` ExperimentsMetricV2DTODataAttributesPercentileAggregationWarehouseMetricMeasure: Warehouse measure that supplies values for the metric. - `id` string: ID of the measure. - `pipeline_column_suffix` string: Suffix used to identify this value in pipeline output columns. - `reference_url` string: URL with supporting information about the metric. - `updated_at` string, date-time: Time when this resource was last updated. - `id` string, uuid, required: ID of the metric. - `type` 'metrics', required: The metric resource type. ## Other responses - `400`: Malformed body, validation failure, or an aggregation that does not match metric_type. - `401`: Missing or invalid authentication. - `403`: Caller lacks product_analytics_metrics_write. - `409`: Another metric in this organization already uses one of these values. - `415`: Request body sent with a media type other than application/json or application/vnd.api+json. - `429`: Too many requests --- [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)