Update a metric

posthttps://statsigapi.net/console/v1/metrics/{id}

Authorizations

STATSIG-API-KEYstringrequired

apiKey (header)

Path parameters

idstringrequired

id

Body

application/json
namestring

The name of the metric, serving as its primary identifier.

descriptionstring

A detailed description of the metric, providing insights into its purpose and application.

tagsstring[]

An array of tags associated with the metric, used for categorization and easier retrieval.

isVerifiedboolean

Flag to mark the metric as verified, ensuring it is deemed trustworthy within the organization.

isReadOnlyboolean

Specifies if the metric definition can only be edited via the Console API, enhancing control over modifications.

isPermanentboolean

Determines if the metric is permanent, preventing it from being deleted or modified inadvertently.

warehouseNativeobject

Optional configuration for metrics utilizing Warehouse Native features, defining specific behaviors and criteria.

Show child attributes
aggregationstring

Allowed: count┃sum┃mean┃daily_participation┃ratio┃funnel┃count_distinct┃percentile

metricSourceNamestring

Deprecated: use metricSources instead. If provided, this will overwrite all metric sources. For Count, Sum, Mean, User Count aggregation types: the name of metric source

criteriaobject[]

Deprecated: use metricSources instead. If provided with metricSourceName, this will overwrite all metric sources. Filtering criteria for the metric source

type[]stringrequired

Type of event criterion for filtering metrics. Options include value, metadata, user, and user_custom; in Warehouse Native, this should always be metadata.

column[]string

Optional column specifying which data attribute to filter on.

condition[]stringrequired

sql_filter, start_withs, ends_with, after_exposure, and before_exposure are only applicable in Warehouse Native

values[]string[]

Optional array of values for the criterion to match against.

nullVacuousOverride[]boolean

If true, overrides null values in criterion evaluation.

metricSourcesobject[]

List of metric sources for this metric.

metricSourceName[]stringrequired
criteria[]unknown[]required

Filtering criteria for the metric source

valueColumn[]string
waitForCohortWindowboolean
denominatorCriteriaunknown[]

Filtering criteria for the denominator metric source for a ratio, or the start event for a retention metric if useSecondaryRetentionEvent is set

denominatorAggregationstring

Allowed: count┃sum┃mean┃daily_participation┃ratio┃funnel┃count_distinct┃percentile

denominatorCustomRollupEndnumber

Custom end window for ratio denominator unit count metrics with "custom" rollup time window. Measured in days or minutes depending on the "denominatorCustomRollupMeasureInMinutes" flag.

denominatorCustomRollupStartnumber

Custom start window for ratio denominator unit count metrics with "custom" rollup time window. Measured in days or minutes depending on the "denominatorCustomRollupMeasureInMinutes" flag.

denominatorMetricSourceNamestring

Name of the metric source for the denominator of a ratio, or the start event for a retention metric if useSecondaryRetentionEvent is set

denominatorRollupTimeWindowstring

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

denominatorValueColumnstring

Column name for the denominator’s value.

funnelCalculationWindownumber

Duration for counting funnel events in days.

funnelCountDistinctstring

Allowed: users┃sessions for distinct count method in funnel events.

funnelEventsobject[]

List of funnel events with associated criteria and identifiers.

criteria[]unknown[]

Optional array of criteria to filter the funnel events, defined by various types and conditions.

metricSourceName[]string

Optional name of the metric source associated with the funnel event.

name[]string

Optional step name for the funnel event, can be null if not specified.

sessionIdentifierField[]string

Name of column which being used as session identifier. Funnel event with the same metric source

funnelStartCriteriastring

Allowed: start_event┃exposure to determine funnel start criteria.

metricDimensionColumnsstring[]

Specify metadata columns for breaking down metric analysis.

metricDimensionLimitsobject[]

Per-dimension breakdown limits; values beyond the limit are grouped into OTHER.

name[]stringrequired

Name of the metadata dimension to apply a breakdown limit.

limit[]integerrequired

Maximum number of values to retain for this dimension (0-100).

metricBakeDaysnumber

Number of days for metric baking; specify duration for analysis.

loadingWindownumber

Lookback window in days for loading metric data. Defaults to 90 days.

numeratorAggregationstring

Aggregation type for numerator; Allowed: count┃sum┃mean┃daily_participation┃ratio┃funnel┃count_distinct┃percentile.

valueColumnstring

Deprecated: use metricSources instead. If provided with metricSourceName, this will overwrite all metric sources. Column name representing the metric’s value.

valueThresholdnumber

Threshold value for filtering metrics.

allowNullRatioDenominatorboolean

Include units which do not have a denominator. Only applicable to ratios.

funnelStrictOrderingboolean
funnelUseExposureAsFirstEventboolean
funnelTimestampAllowanceMsnumber
funnelTimeToConvertboolean
winsorizationHighnumber

High threshold for winsorization; must be between 0 and 1.

winsorizationLownumber

Low threshold for winsorization; must be between 0 and 1.

winsorizationHighDenominatornumber
winsorizationLowDenominatornumber
cupedAttributionWindownumber

Attribution window for CUPED adjustments in days.

rollupTimeWindowstring

Rollup-mode for unit count metrics. Allowed values: "daily" for daily participation rate, "max" for one-time event, "custom" for a custom attribution window

customRollUpStartnumber

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.

customRollUpEndnumber

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.

onlyIncludeUsersWithConversionEventboolean

Flag to include only users with a conversion event in the metric.

denominatorCustomRollupMeasureInMinutesboolean

Flag to measure the denominator custom rollup window in minutes instead of days.

customRollupMeasureInMinutesboolean

Flag to measure the custom rollup window in minutes instead of days.

percentilenumber

Percentile value for statistical calculations.

useLogTransformboolean

Use log transform for the metric.

useSecondaryRetentionEventboolean

Use a different start and completion event for retention calculations.

retentionEndnumber

Retention end in days.

retentionLengthnumber

Retention lookback window in days.

logTransformBasenumber

Log transform base to be used for the metric.

capnumber

Maximum cap for metric values.

surrogateMetricMSEnumber

Mean Squared Error for surrogate metric.

componentsobject[]

Components for composite metrics, defining each component of the formula

operator[]stringrequired

Operator for this component

aggregation[]string

Aggregation type for this component

metricSourceName[]string

Metric source name for this component

name[]string

Optional name for this component

criteria[]unknown[]

Optional filtering criteria for this component

valueColumn[]string

Value column for this component

unitTypesstring[]

Array of unit types that the metric can utilize, such as stableID, userID, or other custom identifiers.

percentilenumber

Updated percentile value for percentile metrics.

scheduledReloadHourinteger

Warehouse Native only - UTC hour at which to run scheduled metric reloads.

scheduledReloadDaysinteger[]

Warehouse Native only - days on which to run scheduled metric reloads from 0 to 6, 0 meaning Sunday. Null to run reloads on all days.

teamstring

Optional field indicating the team name responsible for the metric, aiding in accountability and management.

teamIDstring

Optional field indicating the team ID responsible for the metric, aiding in accountability and management.

directionalitystring

Indicates the desired change direction for the metric. Use "increase" for positive changes and "decrease" for negative changes.

dryRunboolean

Skips persisting updates to the metric (used to validate that inputs are correct)

ownerobject
Show child attributes
emailstring

Email of the updated owner responsible for the metric’s management.

ownerIDstring

ID of the updated owner responsible for the metric’s management.

Response

application/json
200· Update metric response
messagestringrequired

A simple string explaining the result of the operation.

dataobjectrequired
Show child attributes
namestringrequired

The name of the metric, serving as its primary identifier.

typestringrequired

The type of the metric, defining its aggregation method and characteristics.

isVerifiedboolean

Marks the metric as verified, indicating trustworthiness within the organization.

isReadOnlyboolean

Set to true to make the metric definition editable only through the Console API.

unitTypesstring[]

Array of unit types associated with the metric, such as stableID or userID.

metricEventsobject[]

An array of event definitions used to compute the metric. For ratio metrics, each event must use count or count_distinct aggregation.

name[]stringrequired

The name of the metric event.

type[]string

Aggregation type for the metric event. Allowed values: count, count_distinct, value, metadata. For ratio metrics, only count and count_distinct are valid. Do not confuse with criteria[].type, which is a filter condition type.

metadataKey[]string

The key for associated metadata, if applicable.

criteria[]object[]

Filtering criteria for the metric event, including conditions and values to refine the event data.

type[]stringrequired

Type of event criterion for filtering metrics. Options include value, metadata, user, and user_custom; in Warehouse Native, this should always be metadata.

column[]string

Optional column specifying which data attribute to filter on.

condition[]stringrequired

sql_filter, start_withs, ends_with, after_exposure, and before_exposure are only applicable in Warehouse Native

values[]string[]

Optional array of values for the criterion to match against.

nullVacuousOverride[]boolean

If true, overrides null values in criterion evaluation.

metricComponentMetricsobject[]

List of input metrics used to calculate the new metric for composite types.

name[]stringrequired
type[]stringrequired
descriptionstring

An optional description providing additional context about the metric.

directionalitystringrequired

Specifies the desired directionality for the metric, indicating whether an increase or decrease is favorable.

tagsstring[]

Optional tags for categorizing the metric and improving searchability.

isPermanentboolean

Indicates whether the metric is permanent and should not be deleted.

rollupTimeWindowstring

Time window for the metric rollup. Specify "custom" for a customized time window.

customRollUpStartnumber

Custom time window start date in days since exposure.

customRollUpEndnumber

Custom time window end date in days since exposure.

percentilenumber

Percentile value for percentile metrics.

funnelEventListobject[]

List of events used to create funnel metrics.

name[]stringrequired

The name of the funnel event used in the metric.

type[]stringrequired

The type of funnel event, specifying how the event is tracked.

funnelCountDistinctstring

Specifies whether to count events or distinct users for the funnel metric.

warehouseNativeobject

Defines warehouse native metrics for advanced configurations.

aggregationstring

Allowed: count┃sum┃mean┃daily_participation┃ratio┃funnel┃count_distinct┃percentile

metricSourceNamestring

Deprecated: use metricSources instead. If provided, this will overwrite all metric sources. For Count, Sum, Mean, User Count aggregation types: the name of metric source

criteriaunknown[]

Deprecated: use metricSources instead. If provided with metricSourceName, this will overwrite all metric sources. Filtering criteria for the metric source

metricSourcesobject[]

List of metric sources for this metric.

metricSourceName[]stringrequired
criteria[]unknown[]required

Filtering criteria for the metric source

valueColumn[]string
waitForCohortWindowboolean
denominatorCriteriaunknown[]

Filtering criteria for the denominator metric source for a ratio, or the start event for a retention metric if useSecondaryRetentionEvent is set

denominatorAggregationstring

Allowed: count┃sum┃mean┃daily_participation┃ratio┃funnel┃count_distinct┃percentile

denominatorCustomRollupEndnumber

Custom end window for ratio denominator unit count metrics with "custom" rollup time window. Measured in days or minutes depending on the "denominatorCustomRollupMeasureInMinutes" flag.

denominatorCustomRollupStartnumber

Custom start window for ratio denominator unit count metrics with "custom" rollup time window. Measured in days or minutes depending on the "denominatorCustomRollupMeasureInMinutes" flag.

denominatorMetricSourceNamestring

Name of the metric source for the denominator of a ratio, or the start event for a retention metric if useSecondaryRetentionEvent is set

denominatorRollupTimeWindowstring

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

denominatorValueColumnstring

Column name for the denominator’s value.

funnelCalculationWindownumber

Duration for counting funnel events in days.

funnelCountDistinctstring

Allowed: users┃sessions for distinct count method in funnel events.

funnelEventsobject[]

List of funnel events with associated criteria and identifiers.

criteria[]unknown[]

Optional array of criteria to filter the funnel events, defined by various types and conditions.

metricSourceName[]string

Optional name of the metric source associated with the funnel event.

name[]string

Optional step name for the funnel event, can be null if not specified.

sessionIdentifierField[]string

Name of column which being used as session identifier. Funnel event with the same metric source

funnelStartCriteriastring

Allowed: start_event┃exposure to determine funnel start criteria.

metricDimensionColumnsstring[]

Specify metadata columns for breaking down metric analysis.

metricDimensionLimitsobject[]

Per-dimension breakdown limits; values beyond the limit are grouped into OTHER.

name[]stringrequired

Name of the metadata dimension to apply a breakdown limit.

limit[]integerrequired

Maximum number of values to retain for this dimension (0-100).

metricBakeDaysnumber

Number of days for metric baking; specify duration for analysis.

loadingWindownumber

Lookback window in days for loading metric data. Defaults to 90 days.

numeratorAggregationstring

Aggregation type for numerator; Allowed: count┃sum┃mean┃daily_participation┃ratio┃funnel┃count_distinct┃percentile.

valueColumnstring

Deprecated: use metricSources instead. If provided with metricSourceName, this will overwrite all metric sources. Column name representing the metric’s value.

valueThresholdnumber

Threshold value for filtering metrics.

allowNullRatioDenominatorboolean

Include units which do not have a denominator. Only applicable to ratios.

funnelStrictOrderingboolean
funnelUseExposureAsFirstEventboolean
funnelTimestampAllowanceMsnumber
funnelTimeToConvertboolean
winsorizationHighnumber

High threshold for winsorization; must be between 0 and 1.

winsorizationLownumber

Low threshold for winsorization; must be between 0 and 1.

winsorizationHighDenominatornumber
winsorizationLowDenominatornumber
cupedAttributionWindownumber

Attribution window for CUPED adjustments in days.

rollupTimeWindowstring

Rollup-mode for unit count metrics. Allowed values: "daily" for daily participation rate, "max" for one-time event, "custom" for a custom attribution window

customRollUpStartnumber

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.

customRollUpEndnumber

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.

onlyIncludeUsersWithConversionEventboolean

Flag to include only users with a conversion event in the metric.

denominatorCustomRollupMeasureInMinutesboolean

Flag to measure the denominator custom rollup window in minutes instead of days.

customRollupMeasureInMinutesboolean

Flag to measure the custom rollup window in minutes instead of days.

percentilenumber

Percentile value for statistical calculations.

useLogTransformboolean

Use log transform for the metric.

useSecondaryRetentionEventboolean

Use a different start and completion event for retention calculations.

retentionEndnumber

Retention end in days.

retentionLengthnumber

Retention lookback window in days.

logTransformBasenumber

Log transform base to be used for the metric.

capnumber

Maximum cap for metric values.

surrogateMetricMSEnumber

Mean Squared Error for surrogate metric.

componentsobject[]

Components for composite metrics, defining each component of the formula

operator[]stringrequired

Operator for this component

aggregation[]string

Aggregation type for this component

metricSourceName[]string

Metric source name for this component

name[]string

Optional name for this component

criteria[]unknown[]

Optional filtering criteria for this component

valueColumn[]string

Value column for this component

teamstring

The team associated with the metric, applicable for enterprise environments.

teamIDstring

The team ID associated with the metric, applicable for enterprise environments.

dryRunboolean

Skips persisting the metric (used to validate that inputs are correct)

idstringrequired

Unique identifier for the metric, used for referencing within the system.

isHiddenboolean

Indicates if the metric is hidden from the user interface.

lineageobjectrequired
eventsstring[]required

List of event names that contribute to the metric’s calculation.

metricsstring[]required

List of metric names that are part of this metric’s lineage.

creatorNamestring

Name of the person who created the metric, if available.

creatorEmailstring

Email address of the metric creator for contact purposes.

createdTimenumber

Timestamp indicating when the metric was created.

lastModifierIDstring

ID of the last modifier.

lastModifiedTimenumber

Time of the last modification to this metric.

lastModifierEmailstring

Email of the last modifier.

lastModifierNamestring

Name of the last modifier.

scheduledReloadHourinteger

Warehouse Native only - UTC hour at which to run scheduled metric reloads.

scheduledReloadDaysinteger[]

Warehouse Native only - days on which to run scheduled metric reloads from 0 to 6, 0 meaning Sunday. Null to run reloads on all days.

ownerobject
ownerIDstring

ID of the owner

ownerTypestring

Type of the owner (e.g., SDK_KEY or USER)

ownerNamestring

The name of the owner. This field is optional.

ownerEmailstring

The email of the owner. This field is optional.

namestringrequired

The name of the owner.

permalinkstringrequired

A permalink to this metric in the Statsig Console.

401· This endpoint only accepts an active CONSOLE key, but an invalid key was sent. Key: console-xxxXXXxxxXXXxxx
statusintegerrequired
messagestringrequired
404· Not Found. The requested resource could not be found.
statusintegerrequired
messagestringrequired

Was this helpful?