curl --request POST \
--url https://statsigapi.net/console/v1/metrics \
--header 'Content-Type: application/json' \
--header 'STATSIG-API-KEY: <api-key>' \
--data '
{
"name": "metricName",
"type": "sum",
"isVerified": false,
"isReadOnly": false,
"unitTypes": [
"stableID",
"userID"
],
"metricEvents": [
{
"name": "event1",
"type": "value"
}
],
"metricComponentMetrics": [],
"description": "<string>",
"directionality": "increase",
"tags": [
"tag1",
"tag2"
],
"isPermanent": false,
"rollupTimeWindow": "custom",
"customRollUpStart": 1,
"customRollUpEnd": 1,
"funnelEventList": [
{
"name": "event1",
"type": "event_dau"
}
],
"funnelCountDistinct": "events",
"warehouseNative": {
"aggregation": "count",
"metricSourceName": "<string>",
"criteria": [
{
"type": "value",
"condition": "in",
"column": "<string>",
"values": [
"<string>"
],
"nullVacuousOverride": true
}
],
"metricSources": [
{
"metricSourceName": "<string>",
"criteria": [
{
"type": "value",
"condition": "in",
"column": "<string>",
"values": [
"<string>"
],
"nullVacuousOverride": true
}
],
"valueColumn": "<string>"
}
],
"waitForCohortWindow": true,
"denominatorCriteria": [
{
"type": "value",
"condition": "in",
"column": "<string>",
"values": [
"<string>"
],
"nullVacuousOverride": true
}
],
"denominatorAggregation": "count",
"denominatorCustomRollupEnd": 123,
"denominatorCustomRollupStart": 123,
"denominatorMetricSourceName": "<string>",
"denominatorRollupTimeWindow": "<string>",
"denominatorValueColumn": "<string>",
"funnelCalculationWindow": 123,
"funnelCountDistinct": "sessions",
"funnelEvents": [
{
"criteria": [
{
"type": "value",
"condition": "in",
"column": "<string>",
"values": [
"<string>"
],
"nullVacuousOverride": true
}
],
"metricSourceName": "<string>",
"name": "<string>",
"sessionIdentifierField": "<string>"
}
],
"funnelStartCriteria": "start_event",
"metricDimensionColumns": [
"<string>"
],
"metricBakeDays": 123,
"numeratorAggregation": "count",
"valueColumn": "<string>",
"valueThreshold": 123,
"allowNullRatioDenominator": true,
"funnelStrictOrdering": true,
"funnelUseExposureAsFirstEvent": true,
"funnelTimestampAllowanceMs": 123,
"funnelTimeToConvert": true,
"winsorizationHigh": 0.5,
"winsorizationLow": 0.5,
"winsorizationHighDenominator": 0.5,
"winsorizationLowDenominator": 0.5,
"cupedAttributionWindow": 123,
"rollupTimeWindow": "<string>",
"customRollUpStart": 123,
"customRollUpEnd": 123,
"onlyIncludeUsersWithConversionEvent": true,
"denominatorCustomRollupMeasureInMinutes": true,
"customRollupMeasureInMinutes": true,
"percentile": 123,
"useLogTransform": true,
"useSecondaryRetentionEvent": true,
"retentionEnd": 123,
"retentionLength": 123,
"logTransformBase": 123,
"cap": 123,
"surrogateMetricMSE": 123
},
"team": "<string>",
"teamID": "<string>",
"dryRun": true
}
'{
"message": "Metric created successfully.",
"data": {
"id": "TestMetricCapi::sum",
"name": "TestMetricCapi",
"directionality": "increase",
"type": "sum",
"description": "Capi Metric",
"isPermanent": false,
"isReadOnly": false,
"isHidden": false,
"isVerified": false,
"tags": [],
"creatorName": "CONSOLE API",
"creatorEmail": null,
"createdTime": 1720218271796,
"owner": {
"name": "John Doe",
"ownerID": "user123",
"ownerType": "USER",
"ownerName": "John Doe",
"ownerEmail": "[email protected]"
},
"lineage": {
"events": [
"add_to_cart"
],
"metrics": []
},
"team": "Console Team",
"unitTypes": [
"userID"
],
"metricEvents": [
{
"name": "add_to_cart",
"type": "metadata",
"criteria": []
}
]
}
}curl --request POST \
--url https://statsigapi.net/console/v1/metrics \
--header 'Content-Type: application/json' \
--header 'STATSIG-API-KEY: <api-key>' \
--data '
{
"name": "metricName",
"type": "sum",
"isVerified": false,
"isReadOnly": false,
"unitTypes": [
"stableID",
"userID"
],
"metricEvents": [
{
"name": "event1",
"type": "value"
}
],
"metricComponentMetrics": [],
"description": "<string>",
"directionality": "increase",
"tags": [
"tag1",
"tag2"
],
"isPermanent": false,
"rollupTimeWindow": "custom",
"customRollUpStart": 1,
"customRollUpEnd": 1,
"funnelEventList": [
{
"name": "event1",
"type": "event_dau"
}
],
"funnelCountDistinct": "events",
"warehouseNative": {
"aggregation": "count",
"metricSourceName": "<string>",
"criteria": [
{
"type": "value",
"condition": "in",
"column": "<string>",
"values": [
"<string>"
],
"nullVacuousOverride": true
}
],
"metricSources": [
{
"metricSourceName": "<string>",
"criteria": [
{
"type": "value",
"condition": "in",
"column": "<string>",
"values": [
"<string>"
],
"nullVacuousOverride": true
}
],
"valueColumn": "<string>"
}
],
"waitForCohortWindow": true,
"denominatorCriteria": [
{
"type": "value",
"condition": "in",
"column": "<string>",
"values": [
"<string>"
],
"nullVacuousOverride": true
}
],
"denominatorAggregation": "count",
"denominatorCustomRollupEnd": 123,
"denominatorCustomRollupStart": 123,
"denominatorMetricSourceName": "<string>",
"denominatorRollupTimeWindow": "<string>",
"denominatorValueColumn": "<string>",
"funnelCalculationWindow": 123,
"funnelCountDistinct": "sessions",
"funnelEvents": [
{
"criteria": [
{
"type": "value",
"condition": "in",
"column": "<string>",
"values": [
"<string>"
],
"nullVacuousOverride": true
}
],
"metricSourceName": "<string>",
"name": "<string>",
"sessionIdentifierField": "<string>"
}
],
"funnelStartCriteria": "start_event",
"metricDimensionColumns": [
"<string>"
],
"metricBakeDays": 123,
"numeratorAggregation": "count",
"valueColumn": "<string>",
"valueThreshold": 123,
"allowNullRatioDenominator": true,
"funnelStrictOrdering": true,
"funnelUseExposureAsFirstEvent": true,
"funnelTimestampAllowanceMs": 123,
"funnelTimeToConvert": true,
"winsorizationHigh": 0.5,
"winsorizationLow": 0.5,
"winsorizationHighDenominator": 0.5,
"winsorizationLowDenominator": 0.5,
"cupedAttributionWindow": 123,
"rollupTimeWindow": "<string>",
"customRollUpStart": 123,
"customRollUpEnd": 123,
"onlyIncludeUsersWithConversionEvent": true,
"denominatorCustomRollupMeasureInMinutes": true,
"customRollupMeasureInMinutes": true,
"percentile": 123,
"useLogTransform": true,
"useSecondaryRetentionEvent": true,
"retentionEnd": 123,
"retentionLength": 123,
"logTransformBase": 123,
"cap": 123,
"surrogateMetricMSE": 123
},
"team": "<string>",
"teamID": "<string>",
"dryRun": true
}
'{
"message": "Metric created successfully.",
"data": {
"id": "TestMetricCapi::sum",
"name": "TestMetricCapi",
"directionality": "increase",
"type": "sum",
"description": "Capi Metric",
"isPermanent": false,
"isReadOnly": false,
"isHidden": false,
"isVerified": false,
"tags": [],
"creatorName": "CONSOLE API",
"creatorEmail": null,
"createdTime": 1720218271796,
"owner": {
"name": "John Doe",
"ownerID": "user123",
"ownerType": "USER",
"ownerName": "John Doe",
"ownerEmail": "[email protected]"
},
"lineage": {
"events": [
"add_to_cart"
],
"metrics": []
},
"team": "Console Team",
"unitTypes": [
"userID"
],
"metricEvents": [
{
"name": "add_to_cart",
"type": "metadata",
"criteria": []
}
]
}
}Optional header to respect review settings for mutation endpoints.
The name of the new metric, which identifies it within the system.
4 - 200"metricName"
ratio, mean, event_count_custom, event_user, funnel, composite, composite_sum, sum, undefined, user_warehouse "sum"
Marks the metric as verified for internal trustworthiness.
false
Set to true to make the metric definition editable only from the Console API.
false
Array of unit types associated with the metric, such as stableID or userID.
["stableID", "userID"]An array of event definitions used to compute the metric.
Show child attributes
The name of the metric event.
The type of metric event. Allowed values include: count, count_distinct, value, and metadata.
count, count_distinct, value, metadata The key for associated metadata, if applicable.
Filtering criteria for the metric event, including conditions and values to refine the event data.
Show child attributes
Type of event criterion for filtering metrics. Options include value, metadata, user, and user_custom; in Warehouse Native, this should always be metadata.
value, metadata, user, user_custom sql_filter, start_withs, ends_with, after_exposure, and before_exposure are only applicable in Warehouse Native
in, not_in, =, >, <, >=, <=, is_null, non_null, contains, not_contains, sql_filter, starts_with, ends_with, after_exposure, before_exposure, is_true, is_false Optional column specifying which data attribute to filter on.
Optional array of values for the criterion to match against.
If true, overrides null values in criterion evaluation.
[{ "name": "event1", "type": "value" }]A description of the new metric, providing context and purpose.
1000Indicates the desired change direction for the metric. Use "increase" for positive changes and "decrease" for negative changes.
increase, decrease "increase"
Tags associated with the metric for categorization and searchability.
["tag1", "tag2"]Indicates whether the metric is permanent and should not be deleted.
false
Time window for the metric rollup. Specify "custom" for a customized time window.
"custom"
Custom time window start date in days since exposure.
1
Custom time window end date in days since exposure.
1
List of events used to create funnel metrics.
Show child attributes
Specifies whether to count events or distinct users for the funnel metric.
events, users Defines warehouse native metrics for advanced configurations.
Show child attributes
Allowed: count┃sum┃mean┃daily_participation┃ratio┃funnel┃count_distinct┃percentile
count, sum, mean, daily_participation, ratio, funnel, count_distinct, percentile, first_value, latest_value, retention, max, min, For Count, Sum, Mean, User Count aggregation types: the name of metric source
Filtering criteria for the metric source
Show child attributes
Type of event criterion for filtering metrics. Options include value, metadata, user, and user_custom; in Warehouse Native, this should always be metadata.
value, metadata, user, user_custom sql_filter, start_withs, ends_with, after_exposure, and before_exposure are only applicable in Warehouse Native
in, not_in, =, >, <, >=, <=, is_null, non_null, contains, not_contains, sql_filter, starts_with, ends_with, after_exposure, before_exposure, is_true, is_false Optional column specifying which data attribute to filter on.
Optional array of values for the criterion to match against.
If true, overrides null values in criterion evaluation.
List of metric sources for this metric. This field is readonly.
Show child attributes
Filtering criteria for the metric source
Show child attributes
Type of event criterion for filtering metrics. Options include value, metadata, user, and user_custom; in Warehouse Native, this should always be metadata.
value, metadata, user, user_custom sql_filter, start_withs, ends_with, after_exposure, and before_exposure are only applicable in Warehouse Native
in, not_in, =, >, <, >=, <=, is_null, non_null, contains, not_contains, sql_filter, starts_with, ends_with, after_exposure, before_exposure, is_true, is_false Optional column specifying which data attribute to filter on.
Optional array of values for the criterion to match against.
If true, overrides null values in criterion evaluation.
Filtering criteria for the denominator metric source, if this metric is a ratio
Show child attributes
Type of event criterion for filtering metrics. Options include value, metadata, user, and user_custom; in Warehouse Native, this should always be metadata.
value, metadata, user, user_custom sql_filter, start_withs, ends_with, after_exposure, and before_exposure are only applicable in Warehouse Native
in, not_in, =, >, <, >=, <=, is_null, non_null, contains, not_contains, sql_filter, starts_with, ends_with, after_exposure, before_exposure, is_true, is_false Optional column specifying which data attribute to filter on.
Optional array of values for the criterion to match against.
If true, overrides null values in criterion evaluation.
Allowed: count┃sum┃mean┃daily_participation┃ratio┃funnel┃count_distinct┃percentile
count, sum, mean, daily_participation, ratio, funnel, count_distinct, percentile, first_value, latest_value, retention, max, min, Custom end window for ratio denominator unit count metrics with "custom" rollup time window. Measured in days or minutes depending on the "denominatorCustomRollupMeasureInMinutes" flag.
Custom start window for ratio denominator unit count metrics with "custom" rollup time window. Measured in days or minutes depending on the "denominatorCustomRollupMeasureInMinutes" flag.
Name of the metric source for the denominator.
Rollup-mode for ratio denominator unit count metrics. Allowed values: "daily" for daily participation rate, "max" for one-time event, "custom" for a custom attribution window
Column name for the denominator’s value.
Duration for counting funnel events in days.
Allowed: users┃sessions for distinct count method in funnel events.
sessions, users List of funnel events with associated criteria and identifiers.
Show child attributes
Optional array of criteria to filter the funnel events, defined by various types and conditions.
Show child attributes
Type of event criterion for filtering metrics. Options include value, metadata, user, and user_custom; in Warehouse Native, this should always be metadata.
value, metadata, user, user_custom sql_filter, start_withs, ends_with, after_exposure, and before_exposure are only applicable in Warehouse Native
in, not_in, =, >, <, >=, <=, is_null, non_null, contains, not_contains, sql_filter, starts_with, ends_with, after_exposure, before_exposure, is_true, is_false Optional column specifying which data attribute to filter on.
Optional array of values for the criterion to match against.
If true, overrides null values in criterion evaluation.
Optional name of the metric source associated with the funnel event.
Optional step name for the funnel event, can be null if not specified.
Name of column which being used as session identifier. Funnel event with the same metric source
Allowed: start_event┃exposure to determine funnel start criteria.
start_event, exposure Specify metadata columns for breaking down metric analysis.
Number of days for metric baking; specify duration for analysis.
Aggregation type for numerator; Allowed: count┃sum┃mean┃daily_participation┃ratio┃funnel┃count_distinct┃percentile.
count, sum, mean, daily_participation, ratio, funnel, count_distinct, percentile, first_value, latest_value, retention, max, min, Column name representing the metric’s value.
Threshold value for filtering metrics.
Include units which do not have a denominator. Only applicable to ratios.
High threshold for winsorization; must be between 0 and 1.
0 <= x <= 1Low threshold for winsorization; must be between 0 and 1.
0 <= x <= 10 <= x <= 10 <= x <= 1Attribution window for CUPED adjustments in days.
Rollup-mode for unit count metrics. Allowed values: "daily" for daily participation rate, "max" for one-time event, "custom" for a custom attribution window
Custom start window for unit count metrics with "custom" rollup time window, or for other metrics with the "Use Cohort Window in Experiments" option on enabled. Measured in days or minutes depending on the "customRollupMeasureInMinutes" flag.
Custom end window for unit count metrics with "custom" rollup time window, or for other metrics with the "Use Cohort Window in Experiments" option on enabled. Measured in days or minutes depending on the "customRollupMeasureInMinutes" flag.
Flag to include only users with a conversion event in the metric.
Flag to measure the denominator custom rollup window in minutes instead of days.
Flag to measure the custom rollup window in minutes instead of days.
Percentile value for statistical calculations.
Use log transform for the metric.
Use secondary retention event.
Retention end.
Retention length.
Log transform base to be used for the metric.
Maximum cap for metric values.
Mean Squared Error for surrogate metric.
The team associated with the metric, applicable for enterprise environments.
The team ID associated with the metric, applicable for enterprise environments.
Skips persisting the metric (used to validate that inputs are correct)
Create metric response
A simple string explaining the result of the operation.
A single result.
Show child attributes
The name of the metric, serving as its primary identifier.
"metricName"
The type of the metric, defining its aggregation method and characteristics.
ratio, sum, composite, mean, event_count_custom, event_user, funnel, undefined, setup_incomplete, composite_sum, import_window, user_warehouse, count_distinct "sum"
Specifies the desired directionality for the metric, indicating whether an increase or decrease is favorable.
increase, decrease "increase"
Unique identifier for the metric, used for referencing within the system.
"metricId"
Marks the metric as verified, indicating trustworthiness within the organization.
false
Set to true to make the metric definition editable only through the Console API.
false
Array of unit types associated with the metric, such as stableID or userID.
["stableID", "userID"]An array of event definitions used to compute the metric.
Show child attributes
The name of the metric event.
The type of metric event. Allowed values include: count, count_distinct, value, and metadata.
count, count_distinct, value, metadata The key for associated metadata, if applicable.
Filtering criteria for the metric event, including conditions and values to refine the event data.
Show child attributes
Type of event criterion for filtering metrics. Options include value, metadata, user, and user_custom; in Warehouse Native, this should always be metadata.
value, metadata, user, user_custom sql_filter, start_withs, ends_with, after_exposure, and before_exposure are only applicable in Warehouse Native
in, not_in, =, >, <, >=, <=, is_null, non_null, contains, not_contains, sql_filter, starts_with, ends_with, after_exposure, before_exposure, is_true, is_false Optional column specifying which data attribute to filter on.
Optional array of values for the criterion to match against.
If true, overrides null values in criterion evaluation.
[{ "name": "event1", "type": "value" }]An optional description providing additional context about the metric.
"the description of this metric"
Optional tags for categorizing the metric and improving searchability.
["tag1", "tag2"]Indicates whether the metric is permanent and should not be deleted.
false
Time window for the metric rollup. Specify "custom" for a customized time window.
"custom"
Custom time window start date in days since exposure.
1
Custom time window end date in days since exposure.
1
List of events used to create funnel metrics.
Show child attributes
The name of the funnel event used in the metric.
"event1"
The type of funnel event, specifying how the event is tracked.
event_dau, event_user, event_count, event_count_custom "event_dau"
Specifies whether to count events or distinct users for the funnel metric.
events, users Defines warehouse native metrics for advanced configurations.
Show child attributes
Allowed: count┃sum┃mean┃daily_participation┃ratio┃funnel┃count_distinct┃percentile
count, sum, mean, daily_participation, ratio, funnel, count_distinct, percentile, first_value, latest_value, retention, max, min, For Count, Sum, Mean, User Count aggregation types: the name of metric source
Filtering criteria for the metric source
Show child attributes
Type of event criterion for filtering metrics. Options include value, metadata, user, and user_custom; in Warehouse Native, this should always be metadata.
value, metadata, user, user_custom sql_filter, start_withs, ends_with, after_exposure, and before_exposure are only applicable in Warehouse Native
in, not_in, =, >, <, >=, <=, is_null, non_null, contains, not_contains, sql_filter, starts_with, ends_with, after_exposure, before_exposure, is_true, is_false Optional column specifying which data attribute to filter on.
Optional array of values for the criterion to match against.
If true, overrides null values in criterion evaluation.
List of metric sources for this metric. This field is readonly.
Show child attributes
Filtering criteria for the metric source
Show child attributes
Type of event criterion for filtering metrics. Options include value, metadata, user, and user_custom; in Warehouse Native, this should always be metadata.
value, metadata, user, user_custom sql_filter, start_withs, ends_with, after_exposure, and before_exposure are only applicable in Warehouse Native
in, not_in, =, >, <, >=, <=, is_null, non_null, contains, not_contains, sql_filter, starts_with, ends_with, after_exposure, before_exposure, is_true, is_false Optional column specifying which data attribute to filter on.
Optional array of values for the criterion to match against.
If true, overrides null values in criterion evaluation.
Filtering criteria for the denominator metric source, if this metric is a ratio
Show child attributes
Type of event criterion for filtering metrics. Options include value, metadata, user, and user_custom; in Warehouse Native, this should always be metadata.
value, metadata, user, user_custom sql_filter, start_withs, ends_with, after_exposure, and before_exposure are only applicable in Warehouse Native
in, not_in, =, >, <, >=, <=, is_null, non_null, contains, not_contains, sql_filter, starts_with, ends_with, after_exposure, before_exposure, is_true, is_false Optional column specifying which data attribute to filter on.
Optional array of values for the criterion to match against.
If true, overrides null values in criterion evaluation.
Allowed: count┃sum┃mean┃daily_participation┃ratio┃funnel┃count_distinct┃percentile
count, sum, mean, daily_participation, ratio, funnel, count_distinct, percentile, first_value, latest_value, retention, max, min, Custom end window for ratio denominator unit count metrics with "custom" rollup time window. Measured in days or minutes depending on the "denominatorCustomRollupMeasureInMinutes" flag.
Custom start window for ratio denominator unit count metrics with "custom" rollup time window. Measured in days or minutes depending on the "denominatorCustomRollupMeasureInMinutes" flag.
Name of the metric source for the denominator.
Rollup-mode for ratio denominator unit count metrics. Allowed values: "daily" for daily participation rate, "max" for one-time event, "custom" for a custom attribution window
Column name for the denominator’s value.
Duration for counting funnel events in days.
Allowed: users┃sessions for distinct count method in funnel events.
sessions, users List of funnel events with associated criteria and identifiers.
Show child attributes
Optional array of criteria to filter the funnel events, defined by various types and conditions.
Show child attributes
Type of event criterion for filtering metrics. Options include value, metadata, user, and user_custom; in Warehouse Native, this should always be metadata.
value, metadata, user, user_custom sql_filter, start_withs, ends_with, after_exposure, and before_exposure are only applicable in Warehouse Native
in, not_in, =, >, <, >=, <=, is_null, non_null, contains, not_contains, sql_filter, starts_with, ends_with, after_exposure, before_exposure, is_true, is_false Optional column specifying which data attribute to filter on.
Optional array of values for the criterion to match against.
If true, overrides null values in criterion evaluation.
Optional name of the metric source associated with the funnel event.
Optional step name for the funnel event, can be null if not specified.
Name of column which being used as session identifier. Funnel event with the same metric source
Allowed: start_event┃exposure to determine funnel start criteria.
start_event, exposure Specify metadata columns for breaking down metric analysis.
Number of days for metric baking; specify duration for analysis.
Aggregation type for numerator; Allowed: count┃sum┃mean┃daily_participation┃ratio┃funnel┃count_distinct┃percentile.
count, sum, mean, daily_participation, ratio, funnel, count_distinct, percentile, first_value, latest_value, retention, max, min, Column name representing the metric’s value.
Threshold value for filtering metrics.
Include units which do not have a denominator. Only applicable to ratios.
High threshold for winsorization; must be between 0 and 1.
0 <= x <= 1Low threshold for winsorization; must be between 0 and 1.
0 <= x <= 10 <= x <= 10 <= x <= 1Attribution window for CUPED adjustments in days.
Rollup-mode for unit count metrics. Allowed values: "daily" for daily participation rate, "max" for one-time event, "custom" for a custom attribution window
Custom start window for unit count metrics with "custom" rollup time window, or for other metrics with the "Use Cohort Window in Experiments" option on enabled. Measured in days or minutes depending on the "customRollupMeasureInMinutes" flag.
Custom end window for unit count metrics with "custom" rollup time window, or for other metrics with the "Use Cohort Window in Experiments" option on enabled. Measured in days or minutes depending on the "customRollupMeasureInMinutes" flag.
Flag to include only users with a conversion event in the metric.
Flag to measure the denominator custom rollup window in minutes instead of days.
Flag to measure the custom rollup window in minutes instead of days.
Percentile value for statistical calculations.
Use log transform for the metric.
Use secondary retention event.
Retention end.
Retention length.
Log transform base to be used for the metric.
Maximum cap for metric values.
Mean Squared Error for surrogate metric.
The team associated with the metric, applicable for enterprise environments.
The team ID associated with the metric, applicable for enterprise environments.
Skips persisting the metric (used to validate that inputs are correct)
Indicates if the metric is hidden from the user interface.
false
Name of the person who created the metric, if available.
"creatorName"
Email address of the metric creator for contact purposes.
"creatorEmail"
Timestamp indicating when the metric was created.
1716230400
ID of the last modifier.
Time of the last modification to this metric.
Email of the last modifier.
Name of the last modifier.
Show child attributes
The name of the owner.
"John Doe"
ID of the owner
"abc123"
Type of the owner (e.g., SDK_KEY or USER)
"USER"
The name of the owner. This field is optional.
"John Doe"
The email of the owner. This field is optional.
Was this page helpful?