Read Metric Definition

Authorizations

STATSIG-API-KEY

string

header

required

Headers

x-respect-review-settings

string

Optional header to respect review settings for mutation endpoints.

Path Parameters

id

string

required

id

Response

200

application/json

Get Metric Definition response

message

string

required

A simple string explaining the result of the operation.

data

object

required

A single result.

Show child attributes

data.name

string

required

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

Example:

"metricName"

data.type

enum<string>

required

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

Available options:

ratio,

sum,

composite,

mean,

event_count_custom,

event_user,

funnel,

undefined,

setup_incomplete,

composite_sum,

import_window,

user_warehouse

Example:

"sum"

data.directionality

enum<string>

required

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

Available options:

increase,

decrease

Example:

"increase"

data.id

string

required

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

Example:

"metricId"

data.lineage

object

required

Show child attributes

data.lineage.events

string[]

required

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

Example:

["event1", "event2"]

data.lineage.metrics

string[]

required

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

Example:

["metric1", "metric2"]

data.isVerified

boolean

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

Example:

false

data.isReadOnly

boolean

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

Example:

false

data.unitTypes

string[]

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

Example:

["stableID", "userID"]

data.metricEvents

object[]

An array of event definitions used to compute the metric.

Show child attributes

data.metricEvents.name

string

required

The name of the metric event.

data.metricEvents.type

enum<string> | null

The type of metric event. Allowed values include: count, count_distinct, value, and metadata.

Available options:

count,

count_distinct,

value,

metadata

data.metricEvents.metadataKey

string

The key for associated metadata, if applicable.

data.metricEvents.criteria

object[]

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

Show child attributes

data.metricEvents.criteria.type

enum<string>

required

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

Available options:

value,

metadata,

user,

user_custom

data.metricEvents.criteria.condition

enum<string>

required

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

Available options:

in,

not_in,

=,

>,

<,

>=,

<=,

is_null,

non_null,

contains,

not_contains,

sql_filter,

starts_with,

ends_with,

after_exposure

data.metricEvents.criteria.column

string

Optional column specifying which data attribute to filter on.

data.metricEvents.criteria.values

string[]

Optional array of values for the criterion to match against.

data.metricEvents.criteria.nullVacuousOverride

boolean

If true, overrides null values in criterion evaluation.

Example:

[{ "name": "event1", "type": "value" }]

data.metricComponentMetrics

object[]

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

Show child attributes

data.metricComponentMetrics.name

string

required

data.metricComponentMetrics.type

string

required

Example:

[]

data.description

string

An optional description providing additional context about the metric.

Example:

"the description of this metric"

data.tags

string[]

Optional tags for categorizing the metric and improving searchability.

Example:

["tag1", "tag2"]

data.isPermanent

boolean

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

Example:

false

data.rollupTimeWindow

string

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

Example:

"custom"

data.customRollUpStart

number

Custom time window start date in days since exposure.

Example:

1

data.customRollUpEnd

number

Custom time window end date in days since exposure.

Example:

1

data.funnelEventList

object[]

List of events used to create funnel metrics.

Show child attributes

data.funnelEventList.name

string

required

The name of the funnel event used in the metric.

Example:

"event1"

data.funnelEventList.type

enum<string>

required

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

Available options:

event_dau,

event_user,

event_count,

event_count_custom

Example:

"event_dau"

data.funnelCountDistinct

enum<string>

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

Available options:

events,

users

data.warehouseNative

object

Defines warehouse native metrics for advanced configurations.

Show child attributes

data.warehouseNative.aggregation

enum<string>

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

Available options:

count,

sum,

mean,

daily_participation,

ratio,

funnel,

count_distinct,

percentile,

first_value,

latest_value,

retention,

max,

min,

data.warehouseNative.metricSourceName

string

For Count, Sum, Mean, User Count aggregation types: the name of metric source

data.warehouseNative.criteria

object[]

Filtering criteria for the metric source

Show child attributes

data.warehouseNative.criteria.type

enum<string>

required

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

Available options:

value,

metadata,

user,

user_custom

data.warehouseNative.criteria.condition

enum<string>

required

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

Available options:

in,

not_in,

=,

>,

<,

>=,

<=,

is_null,

non_null,

contains,

not_contains,

sql_filter,

starts_with,

ends_with,

after_exposure

data.warehouseNative.criteria.column

string

Optional column specifying which data attribute to filter on.

data.warehouseNative.criteria.values

string[]

Optional array of values for the criterion to match against.

data.warehouseNative.criteria.nullVacuousOverride

boolean

If true, overrides null values in criterion evaluation.

data.warehouseNative.waitForCohortWindow

boolean

data.warehouseNative.denominatorCriteria

object[]

Filtering criteria for the denominator metric source, if this metric is a ratio

Show child attributes

data.warehouseNative.denominatorCriteria.type

enum<string>

required

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

Available options:

value,

metadata,

user,

user_custom

data.warehouseNative.denominatorCriteria.condition

enum<string>

required

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

Available options:

in,

not_in,

=,

>,

<,

>=,

<=,

is_null,

non_null,

contains,

not_contains,

sql_filter,

starts_with,

ends_with,

after_exposure

data.warehouseNative.denominatorCriteria.column

string

Optional column specifying which data attribute to filter on.

data.warehouseNative.denominatorCriteria.values

string[]

Optional array of values for the criterion to match against.

data.warehouseNative.denominatorCriteria.nullVacuousOverride

boolean

If true, overrides null values in criterion evaluation.

data.warehouseNative.denominatorAggregation

enum<string>

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

Available options:

count,

sum,

mean,

daily_participation,

ratio,

funnel,

count_distinct,

percentile,

first_value,

latest_value,

retention,

max,

min,

data.warehouseNative.denominatorCustomRollupEnd

number

Custom end date for rollup in days since exposure.

data.warehouseNative.denominatorCustomRollupStart

number

Custom start date for rollup in days since exposure.

data.warehouseNative.denominatorMetricSourceName

string

Name of the metric source for the denominator.

data.warehouseNative.denominatorRollupTimeWindow

string

Time window for the denominator metric. Specify "custom" for a custom window.

data.warehouseNative.denominatorValueColumn

string

Column name for the denominator’s value.

data.warehouseNative.funnelCalculationWindow

number

Duration for counting funnel events in days.

data.warehouseNative.funnelCountDistinct

enum<string>

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

Available options:

sessions,

users

data.warehouseNative.funnelEvents

object[]

List of funnel events with associated criteria and identifiers.

Show child attributes

data.warehouseNative.funnelEvents.criteria

object[]

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

Show child attributes

data.warehouseNative.funnelEvents.criteria.type

enum<string>

required

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

Available options:

value,

metadata,

user,

user_custom

data.warehouseNative.funnelEvents.criteria.condition

enum<string>

required

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

Available options:

in,

not_in,

=,

>,

<,

>=,

<=,

is_null,

non_null,

contains,

not_contains,

sql_filter,

starts_with,

ends_with,

after_exposure

data.warehouseNative.funnelEvents.criteria.column

string

Optional column specifying which data attribute to filter on.

data.warehouseNative.funnelEvents.criteria.values

string[]

Optional array of values for the criterion to match against.

data.warehouseNative.funnelEvents.criteria.nullVacuousOverride

boolean

If true, overrides null values in criterion evaluation.

data.warehouseNative.funnelEvents.metricSourceName

string

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

data.warehouseNative.funnelEvents.name

string | null

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

data.warehouseNative.funnelEvents.sessionIdentifierField

string | null

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

data.warehouseNative.funnelStartCriteria

enum<string>

Allowed: start_event┃exposure to determine funnel start criteria.

Available options:

start_event,

exposure

data.warehouseNative.metricDimensionColumns

string[]

Specify metadata columns for breaking down metric analysis.

data.warehouseNative.metricBakeDays

number

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

data.warehouseNative.numeratorAggregation

enum<string>

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

Available options:

count,

sum,

mean,

daily_participation,

ratio,

funnel,

count_distinct,

percentile,

first_value,

latest_value,

retention,

max,

min,

data.warehouseNative.valueColumn

string

Column name representing the metric’s value.

data.warehouseNative.winsorizationHigh

number

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

Required range: 0 <= x <= 1

data.warehouseNative.winsorizationLow

number

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

Required range: 0 <= x <= 1

data.warehouseNative.cupedAttributionWindow

number | null

Attribution window for CUPED adjustments in days.

data.warehouseNative.onlyIncludeUsersWithConversionEvent

boolean

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

data.warehouseNative.percentile

number

Percentile value for statistical calculations.

data.warehouseNative.valueThreshold

number

Threshold value for filtering metrics.

data.warehouseNative.cap

number

Maximum cap for metric values.

data.warehouseNative.rollupTimeWindow

string

General time window for rollup; can specify custom settings.

data.warehouseNative.customRollUpStart

number

Custom start date for rollup in days since exposure.

data.warehouseNative.customRollUpEnd

number

Custom end date for rollup in days since exposure.

data.warehouseNative.allowNullRatioDenominator

boolean

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

data.team

string | null

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

data.teamID

string | null

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

data.dryRun

boolean

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

data.isHidden

boolean

Indicates if the metric is hidden from the user interface.

Example:

false

data.creatorName

string | null

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

Example:

"creatorName"

data.creatorEmail

string | null

Email address of the metric creator for contact purposes.

Example:

"creatorEmail"

data.createdTime

number

Timestamp indicating when the metric was created.

Example:

1716230400

data.lastModifierID

string | null

ID of the last modifier.

data.lastModifiedTime

number | null

Time of the last modification to this metric.

data.lastModifierEmail

string | null

Email of the last modifier.

data.lastModifierName

string | null

Name of the last modifier.

data.owner

object

Show child attributes

data.owner.name

string

required

Name of the owner responsible for the metric’s management.

Example:

"ownerName"