---
title: "Read Metric Definition"
method: GET
path: "/console/v1/metrics/{id}"
tags: ["Metrics", "Metrics"]
---

# Read Metric Definition

`GET /console/v1/metrics/{id}`

## Path parameters

- `id` string, required

## Response `200`

Get Metric Definition response

- object
  - `message` string, required — A simple string explaining the result of the operation.
  - `data` object, required — A single result.
    - `name` string, required — The name of the metric, serving as its primary identifier.
    - `type` 'ratio' | 'sum' | 'composite' | 'mean' | 'event_count_custom' | 'event_user' | 'event_user_window' | 'funnel' | 'undefined' | 'setup_incomplete' | 'composite_sum' | 'import_window' | 'user_warehouse' | 'hybrid_warehouse' | 'count_distinct' | 'ads_segment_active_users' | 'ads_segment_exposed_user_days' | 'percentile' | 'latest_value', required — The type of the metric, defining its aggregation method and characteristics.
    - `isVerified` boolean — Marks the metric as verified, indicating trustworthiness within the organization.
    - `isReadOnly` boolean — Set to true to make the metric definition editable only through the Console API.
    - `unitTypes` string[] — Array of unit types associated with the metric, such as stableID or userID.
    - `metricEvents` object[] — An array of event definitions used to compute the metric. For ratio metrics, each event must use count or count_distinct aggregation.
      - `name` string, required — The name of the metric event.
      - `type` 'count' | 'count_distinct' | 'value' | 'metadata', nullable — 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` MetricEventsCriteriaDto[] — Filtering criteria for the metric event, including conditions and values to refine the event data.
        - `type` 'value' | 'metadata' | 'user' | 'user_custom', required — 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` 'in' | 'not_in' | '=' | '>' | '<' | '>=' | '<=' | 'is_null' | 'non_null' | 'contains' | 'not_contains' | 'sql_filter' | 'starts_with' | 'ends_with' | 'after_exposure' | 'before_exposure' | 'is_true' | 'is_false', required — 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.
    - `metricComponentMetrics` object[] — List of input metrics used to calculate the new metric for composite types.
      - `name` string, required
      - `type` string, required
    - `description` string — An optional description providing additional context about the metric.
    - `directionality` 'increase' | 'decrease', required — Specifies the desired directionality for the metric, indicating whether an increase or decrease is favorable.
    - `tags` string[] — Optional tags for categorizing the metric and improving searchability.
    - `isPermanent` boolean — Indicates whether the metric is permanent and should not be deleted.
    - `rollupTimeWindow` string — Time window for the metric rollup. Specify "custom" for a customized time window.
    - `customRollUpStart` number, double — Custom time window start date in days since exposure.
    - `customRollUpEnd` number, double — Custom time window end date in days since exposure.
    - `percentile` number, double — Percentile value for percentile metrics.
    - `funnelEventList` object[] — List of events used to create funnel metrics.
      - `name` string, required — The name of the funnel event used in the metric.
      - `type` 'event_dau' | 'event_user' | 'event_count' | 'event_count_custom', required — The type of funnel event, specifying how the event is tracked.
    - `funnelCountDistinct` 'events' | 'users' — Specifies whether to count events or distinct users for the funnel metric.
    - `warehouseNative` object — Defines warehouse native metrics for advanced configurations.
      - `aggregation` 'count' | 'sum' | 'mean' | 'daily_participation' | 'ratio' | 'funnel' | 'count_distinct' | 'percentile' | 'first_value' | 'latest_value' | 'retention' | 'max' | 'min' | 'composite' | '' — Allowed: count┃sum┃mean┃daily_participation┃ratio┃funnel┃count_distinct┃percentile┃first_value┃latest_value┃retention┃max┃min┃composite
      - `metricSourceName` string — 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
      - `criteria` MetricEventsCriteriaDto[] — Deprecated: use `metricSources` instead. If provided with `metricSourceName`, this will overwrite all metric sources. Filtering criteria for the metric source
        - `type` 'value' | 'metadata' | 'user' | 'user_custom', required — 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` 'in' | 'not_in' | '=' | '>' | '<' | '>=' | '<=' | 'is_null' | 'non_null' | 'contains' | 'not_contains' | 'sql_filter' | 'starts_with' | 'ends_with' | 'after_exposure' | 'before_exposure' | 'is_true' | 'is_false', required — 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.
      - `metricSources` object[] — List of metric sources for this metric.
        - `metricSourceName` string, required
        - `criteria` MetricEventsCriteriaDto[], required — Filtering criteria for the metric source
          - `type` 'value' | 'metadata' | 'user' | 'user_custom', required — 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` 'in' | 'not_in' | '=' | '>' | '<' | '>=' | '<=' | 'is_null' | 'non_null' | 'contains' | 'not_contains' | 'sql_filter' | 'starts_with' | 'ends_with' | 'after_exposure' | 'before_exposure' | 'is_true' | 'is_false', required — 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.
        - `valueColumn` string
      - `waitForCohortWindow` boolean
      - `denominatorCriteria` MetricEventsCriteriaDto[] — Filtering criteria for the denominator metric source for a ratio, or the start event for a retention metric if useSecondaryRetentionEvent is set
        - `type` 'value' | 'metadata' | 'user' | 'user_custom', required — 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` 'in' | 'not_in' | '=' | '>' | '<' | '>=' | '<=' | 'is_null' | 'non_null' | 'contains' | 'not_contains' | 'sql_filter' | 'starts_with' | 'ends_with' | 'after_exposure' | 'before_exposure' | 'is_true' | 'is_false', required — 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.
      - `denominatorAggregation` 'count' | 'sum' | 'mean' | 'daily_participation' | 'ratio' | 'funnel' | 'count_distinct' | 'percentile' | 'first_value' | 'latest_value' | 'retention' | 'max' | 'min' | 'composite' | '' — Allowed: count┃sum┃mean┃daily_participation┃ratio┃funnel┃count_distinct┃percentile┃first_value┃latest_value┃retention┃max┃min┃composite
      - `denominatorCustomRollupEnd` number, double — Custom end window for ratio denominator unit count metrics with "custom" rollup time window. Measured in days or minutes depending on the "denominatorCustomRollupMeasureInMinutes" flag.
      - `denominatorCustomRollupStart` number, double — Custom start window for ratio denominator unit count metrics with "custom" rollup time window. Measured in days or minutes depending on the "denominatorCustomRollupMeasureInMinutes" flag.
      - `denominatorMetricSourceName` string — Name of the metric source for the denominator of a ratio, or the start event for a retention metric if useSecondaryRetentionEvent is set
      - `denominatorRollupTimeWindow` string — 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
      - `denominatorValueColumn` string — Column name for the denominator’s value.
      - `funnelCalculationWindow` integer — Duration for counting funnel events in days.
      - `funnelCountDistinct` 'sessions' | 'users' — Allowed: users┃sessions for distinct count method in funnel events.
      - `funnelEvents` object[] — List of funnel events with associated criteria and identifiers.
        - `criteria` MetricEventsCriteriaDto[] — Optional array of criteria to filter the funnel events, defined by various types and conditions.
          - `type` 'value' | 'metadata' | 'user' | 'user_custom', required — 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` 'in' | 'not_in' | '=' | '>' | '<' | '>=' | '<=' | 'is_null' | 'non_null' | 'contains' | 'not_contains' | 'sql_filter' | 'starts_with' | 'ends_with' | 'after_exposure' | 'before_exposure' | 'is_true' | 'is_false', required — 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.
        - `metricSourceName` string — Optional name of the metric source associated with the funnel event.
        - `name` string, nullable — Optional step name for the funnel event, can be null if not specified.
        - `sessionIdentifierField` string, nullable — Name of column which being used as session identifier. Funnel event with the same metric source
      - `funnelStartCriteria` 'start_event' | 'exposure' — Allowed: start_event┃exposure to determine funnel start criteria.
      - `metricDimensionColumns` string[] — Specify metadata columns for breaking down metric analysis.
      - `metricDimensionLimits` object[] — Per-dimension breakdown limits; values beyond the limit are grouped into OTHER.
        - `name` string, required — Name of the metadata dimension to apply a breakdown limit.
        - `limit` integer, required — Maximum number of values to retain for this dimension (0-100).
      - `metricBakeDays` integer — Number of days for metric baking; specify duration for analysis.
      - `loadingWindow` integer — Lookback window in days for loading metric data. Defaults to 90 days.
      - `numeratorAggregation` 'count' | 'sum' | 'mean' | 'daily_participation' | 'ratio' | 'funnel' | 'count_distinct' | 'percentile' | 'first_value' | 'latest_value' | 'retention' | 'max' | 'min' | 'composite' | '' — Aggregation type for numerator; Allowed: count┃sum┃mean┃daily_participation┃ratio┃funnel┃count_distinct┃percentile.
      - `valueColumn` string — Deprecated: use `metricSources` instead. If provided with `metricSourceName`, this will overwrite all metric sources. Column name representing the metric’s value.
      - `valueThreshold` number, double — Threshold value for filtering metrics.
      - `allowNullRatioDenominator` boolean — Include units which do not have a denominator. Only applicable to ratios.
      - `funnelStrictOrdering` boolean
      - `funnelUseExposureAsFirstEvent` boolean
      - `funnelTimestampAllowanceMs` number, double
      - `funnelTimeToConvert` boolean
      - `winsorizationHigh` number, double — High threshold for winsorization; must be between 0 and 1.
      - `winsorizationLow` number, double — Low threshold for winsorization; must be between 0 and 1.
      - `winsorizationHighDenominator` number, double
      - `winsorizationLowDenominator` number, double
      - `cupedAttributionWindow` integer, nullable — Attribution window for CUPED adjustments in days.
      - `rollupTimeWindow` string — Rollup-mode for unit count metrics. Allowed values: "daily" for daily participation rate, "max" for one-time event, "custom" for a custom attribution window
      - `customRollUpStart` integer — 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.
      - `customRollUpEnd` integer — 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.
      - `onlyIncludeUsersWithConversionEvent` boolean — Flag to include only users with a conversion event in the metric.
      - `denominatorCustomRollupMeasureInMinutes` boolean — Flag to measure the denominator custom rollup window in minutes instead of days.
      - `customRollupMeasureInMinutes` boolean — Flag to measure the custom rollup window in minutes instead of days.
      - `percentile` number, double — Percentile value for statistical calculations.
      - `useLogTransform` boolean — Use log transform for the metric.
      - `useSecondaryRetentionEvent` boolean — Use a different start and completion event for retention calculations.
      - `retentionEnd` integer — Retention end in days.
      - `retentionLength` integer — Retention lookback window in days.
      - `logTransformBase` number, double, nullable — Log transform base to be used for the metric.
      - `cap` number, double — Maximum cap for metric values.
      - `surrogateMetricMSE` number, double, nullable — Mean Squared Error for surrogate metric.
      - `components` object[] — Components for composite metrics, defining each component of the formula
        - `operator` '+' | '-', required — Operator for this component
        - `aggregation` 'count' | 'sum' | 'mean' | 'daily_participation' | 'ratio' | 'funnel' | 'count_distinct' | 'percentile' | 'first_value' | 'latest_value' | 'retention' | 'max' | 'min' | 'composite' | '' — Aggregation type for this component
        - `metricSourceName` string — Metric source name for this component
        - `name` string, nullable — Optional name for this component
        - `criteria` MetricEventsCriteriaDto[] — Optional filtering criteria for this component
          - `type` 'value' | 'metadata' | 'user' | 'user_custom', required — 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` 'in' | 'not_in' | '=' | '>' | '<' | '>=' | '<=' | 'is_null' | 'non_null' | 'contains' | 'not_contains' | 'sql_filter' | 'starts_with' | 'ends_with' | 'after_exposure' | 'before_exposure' | 'is_true' | 'is_false', required — 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.
        - `valueColumn` string — Value column for this component
    - `team` string, nullable — The team associated with the metric, applicable for enterprise environments.
    - `teamID` string, nullable — The team ID associated with the metric, applicable for enterprise environments.
    - `dryRun` boolean — Skips persisting the metric (used to validate that inputs are correct)
    - `id` string, required — Unique identifier for the metric, used for referencing within the system.
    - `isHidden` boolean — Indicates if the metric is hidden from the user interface.
    - `lineage` object, required
      - `events` string[], required — List of event names that contribute to the metric’s calculation.
      - `metrics` string[], required — List of metric names that are part of this metric’s lineage.
    - `creatorName` string, nullable — Name of the person who created the metric, if available.
    - `creatorEmail` string, nullable — Email address of the metric creator for contact purposes.
    - `createdTime` number, double — Timestamp indicating when the metric was created.
    - `lastModifierID` string, nullable — ID of the last modifier.
    - `lastModifiedTime` number, double, nullable — Time of the last modification to this metric.
    - `lastModifierEmail` string, nullable — Email of the last modifier.
    - `lastModifierName` string, nullable — Name of the last modifier.
    - `scheduledReloadHour` integer, nullable — Warehouse Native only - UTC hour at which to run scheduled metric reloads.
    - `scheduledReloadDays` integer[], nullable — 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.
    - `owner` object — Schema for owner data including ID, type, name.
      - `ownerID` string — ID of the owner
      - `ownerType` string — Type of the owner (e.g., SDK_KEY or USER)
      - `ownerName` string — The name of the owner. This field is optional.
      - `ownerEmail` string — The email of the owner. This field is optional.
    - `permalink` string, uri, required — A permalink to this metric in the Statsig Console.

## Other responses

- `404` — Not Found. The requested resource could not be found.

---

[API](https://skmtc.net/statsig/apis/console-api.md) · [All operations](https://skmtc.net/statsig/apis/console-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/statsig/console-api/versions/3189f450c93b/schema)