> ## Documentation Index
> Fetch the complete documentation index at: https://statsig-preview.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Read Metric Definition
## OpenAPI
````yaml api-reference/statsig_openapi.json get /console/v1/metrics/{id}
openapi: 3.0.0
info:
title: Console API
description: >-
The "Console API" is the CRUD API for performing the actions offered on
console.statsig.com without needing to go through the web UI.
If you have any feature requests, drop on in to our [slack
channel](https://www.statsig.com/slack) and let us know.
Authorization
All requests must include the **STATSIG-API-KEY** field in the header. The
value should be a **Console API Key** which can be created in the Project
Settings on
[console.statsig.com/api_keys](https://console.statsig.com/api_keys)
Rate Limiting
Requests to the Console API are limited to ~ 100reqs / 10secs and ~
900reqs / 15 mins.
Keyboard Search
Use Ctrl/Cmd + K to search for specific endpoints.
version: 20240601.0.0
contact: {}
servers:
- url: https://statsigapi.net
security: []
tags: []
paths:
/console/v1/metrics/{id}:
get:
tags:
- Metrics
summary: Read Metric Definition
parameters:
- name: id
required: true
in: path
description: id
schema:
type: string
- name: x-respect-review-settings
in: header
description: Optional header to respect review settings for mutation endpoints.
required: false
schema:
type: string
responses:
'200':
description: Get Metric Definition response
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/SingleDataResponse'
- properties:
data:
$ref: >-
#/components/schemas/ExternalMetricDefinitionContractDto
example:
message: Metric read 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: CONSOLE API
lineage:
events:
- add_to_cart
metrics: []
team: Console Team
unitTypes:
- userID
metricEvents:
- name: add_to_cart
type: metadata
criteria: []
example:
message: Metric read 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: CONSOLE API
lineage:
events:
- add_to_cart
metrics: []
team: Console Team
unitTypes:
- userID
metricEvents:
- name: add_to_cart
type: metadata
criteria: []
'404':
description: Not Found. The requested resource could not be found.
content:
application/json:
schema:
type: object
properties:
status:
type: integer
enum:
- 404
message:
type: string
required:
- status
- message
examples:
Not Found:
value:
status: 404
message: Not Found. The requested resource could not be found.
security:
- STATSIG-API-KEY: []
components:
schemas:
SingleDataResponse:
type: object
properties:
message:
type: string
description: A simple string explaining the result of the operation.
data:
type: object
description: A single result.
required:
- message
- data
ExternalMetricDefinitionContractDto:
type: object
properties:
name:
type: string
description: The name of the metric, serving as its primary identifier.
example: metricName
type:
type: string
enum:
- ratio
- sum
- composite
- mean
- event_count_custom
- event_user
- funnel
- undefined
- setup_incomplete
- composite_sum
- import_window
- user_warehouse
description: >-
The type of the metric, defining its aggregation method and
characteristics.
example: sum
isVerified:
type: boolean
description: >-
Marks the metric as verified, indicating trustworthiness within the
organization.
example: false
isReadOnly:
type: boolean
description: >-
Set to true to make the metric definition editable only through the
Console API.
example: false
unitTypes:
type: array
items:
type: string
description: >-
Array of unit types associated with the metric, such as stableID or
userID.
example:
- stableID
- userID
metricEvents:
type: array
items:
type: object
properties:
name:
type: string
description: The name of the metric event.
type:
type: string
enum:
- count
- count_distinct
- value
- metadata
nullable: true
description: >-
The type of metric event. Allowed values include: count,
count_distinct, value, and metadata.
metadataKey:
type: string
description: The key for associated metadata, if applicable.
criteria:
type: array
items:
type: object
properties:
type:
type: string
enum:
- value
- metadata
- user
- user_custom
description: >-
Type of event criterion for filtering metrics. Options
include `value`, `metadata`, `user`, and `user_custom`;
in Warehouse Native, this should always be `metadata`.
column:
type: string
description: >-
Optional column specifying which data attribute to
filter on.
condition:
type: string
enum:
- in
- not_in
- '='
- '>'
- <
- '>='
- <=
- is_null
- non_null
- contains
- not_contains
- sql_filter
- starts_with
- ends_with
- after_exposure
description: >-
sql_filter, start_withs, ends_with, and after_exposure
are only applicable in Warehouse Native
values:
type: array
items:
type: string
description: >-
Optional array of values for the criterion to match
against.
nullVacuousOverride:
type: boolean
description: If true, overrides null values in criterion evaluation.
required:
- type
- condition
description: >-
Filtering criteria for the metric event, including conditions
and values to refine the event data.
required:
- name
description: An array of event definitions used to compute the metric.
example:
- name: event1
type: value
metricComponentMetrics:
type: array
items:
type: object
properties:
name:
type: string
type:
type: string
required:
- name
- type
description: >-
List of input metrics used to calculate the new metric for composite
types.
example: []
description:
type: string
description: >-
An optional description providing additional context about the
metric.
example: the description of this metric
directionality:
type: string
enum:
- increase
- decrease
description: >-
Specifies the desired directionality for the metric, indicating
whether an increase or decrease is favorable.
example: increase
tags:
type: array
items:
type: string
description: >-
Optional tags for categorizing the metric and improving
searchability.
example:
- tag1
- tag2
isPermanent:
type: boolean
description: Indicates whether the metric is permanent and should not be deleted.
example: false
rollupTimeWindow:
type: string
description: >-
Time window for the metric rollup. Specify "custom" for a customized
time window.
example: custom
customRollUpStart:
type: number
description: Custom time window start date in days since exposure.
example: 1
customRollUpEnd:
type: number
description: Custom time window end date in days since exposure.
example: 1
funnelEventList:
type: array
items:
type: object
properties:
name:
type: string
description: The name of the funnel event used in the metric.
example: event1
type:
type: string
enum:
- event_dau
- event_user
- event_count
- event_count_custom
description: The type of funnel event, specifying how the event is tracked.
example: event_dau
required:
- name
- type
description: List of events used to create funnel metrics.
funnelCountDistinct:
type: string
enum:
- events
- users
description: >-
Specifies whether to count events or distinct users for the funnel
metric.
warehouseNative:
type: object
properties:
aggregation:
type: string
enum:
- count
- sum
- mean
- daily_participation
- ratio
- funnel
- count_distinct
- percentile
- first_value
- latest_value
- retention
- max
- min
- ''
description: >-
Allowed:
count┃sum┃mean┃daily_participation┃ratio┃funnel┃count_distinct┃percentile
metricSourceName:
type: string
description: >-
For Count, Sum, Mean, User Count aggregation types: the name of
metric source
criteria:
type: array
items:
type: object
properties:
type:
type: string
enum:
- value
- metadata
- user
- user_custom
description: >-
Type of event criterion for filtering metrics. Options
include `value`, `metadata`, `user`, and `user_custom`; in
Warehouse Native, this should always be `metadata`.
column:
type: string
description: >-
Optional column specifying which data attribute to filter
on.
condition:
type: string
enum:
- in
- not_in
- '='
- '>'
- <
- '>='
- <=
- is_null
- non_null
- contains
- not_contains
- sql_filter
- starts_with
- ends_with
- after_exposure
description: >-
sql_filter, start_withs, ends_with, and after_exposure are
only applicable in Warehouse Native
values:
type: array
items:
type: string
description: >-
Optional array of values for the criterion to match
against.
nullVacuousOverride:
type: boolean
description: If true, overrides null values in criterion evaluation.
required:
- type
- condition
description: Filtering criteria for the metric source
waitForCohortWindow:
type: boolean
denominatorCriteria:
type: array
items:
type: object
properties:
type:
type: string
enum:
- value
- metadata
- user
- user_custom
description: >-
Type of event criterion for filtering metrics. Options
include `value`, `metadata`, `user`, and `user_custom`; in
Warehouse Native, this should always be `metadata`.
column:
type: string
description: >-
Optional column specifying which data attribute to filter
on.
condition:
type: string
enum:
- in
- not_in
- '='
- '>'
- <
- '>='
- <=
- is_null
- non_null
- contains
- not_contains
- sql_filter
- starts_with
- ends_with
- after_exposure
description: >-
sql_filter, start_withs, ends_with, and after_exposure are
only applicable in Warehouse Native
values:
type: array
items:
type: string
description: >-
Optional array of values for the criterion to match
against.
nullVacuousOverride:
type: boolean
description: If true, overrides null values in criterion evaluation.
required:
- type
- condition
description: >-
Filtering criteria for the denominator metric source, if this
metric is a ratio
denominatorAggregation:
type: string
enum:
- count
- sum
- mean
- daily_participation
- ratio
- funnel
- count_distinct
- percentile
- first_value
- latest_value
- retention
- max
- min
- ''
description: >-
Allowed:
count┃sum┃mean┃daily_participation┃ratio┃funnel┃count_distinct┃percentile
denominatorCustomRollupEnd:
type: number
description: Custom end date for rollup in days since exposure.
denominatorCustomRollupStart:
type: number
description: Custom start date for rollup in days since exposure.
denominatorMetricSourceName:
type: string
description: Name of the metric source for the denominator.
denominatorRollupTimeWindow:
type: string
description: >-
Time window for the denominator metric. Specify "custom" for a
custom window.
denominatorValueColumn:
type: string
description: Column name for the denominator’s value.
funnelCalculationWindow:
type: number
description: Duration for counting funnel events in days.
funnelCountDistinct:
type: string
enum:
- sessions
- users
description: >-
Allowed: users┃sessions for distinct count method in funnel
events.
funnelEvents:
type: array
items:
type: object
properties:
criteria:
type: array
items:
type: object
properties:
type:
type: string
enum:
- value
- metadata
- user
- user_custom
description: >-
Type of event criterion for filtering metrics.
Options include `value`, `metadata`, `user`, and
`user_custom`; in Warehouse Native, this should
always be `metadata`.
column:
type: string
description: >-
Optional column specifying which data attribute to
filter on.
condition:
type: string
enum:
- in
- not_in
- '='
- '>'
- <
- '>='
- <=
- is_null
- non_null
- contains
- not_contains
- sql_filter
- starts_with
- ends_with
- after_exposure
description: >-
sql_filter, start_withs, ends_with, and
after_exposure are only applicable in Warehouse
Native
values:
type: array
items:
type: string
description: >-
Optional array of values for the criterion to match
against.
nullVacuousOverride:
type: boolean
description: >-
If true, overrides null values in criterion
evaluation.
required:
- type
- condition
description: >-
Optional array of criteria to filter the funnel events,
defined by various types and conditions.
metricSourceName:
type: string
description: >-
Optional name of the metric source associated with the
funnel event.
name:
type: string
nullable: true
description: >-
Optional step name for the funnel event, can be null if
not specified.
sessionIdentifierField:
type: string
nullable: true
description: >-
Name of column which being used as session identifier.
Funnel event with the same metric source
description: List of funnel events with associated criteria and identifiers.
funnelStartCriteria:
type: string
enum:
- start_event
- exposure
description: >-
Allowed: start_event┃exposure to determine funnel start
criteria.
metricDimensionColumns:
type: array
items:
type: string
description: Specify metadata columns for breaking down metric analysis.
metricBakeDays:
type: number
description: Number of days for metric baking; specify duration for analysis.
numeratorAggregation:
type: string
enum:
- count
- sum
- mean
- daily_participation
- ratio
- funnel
- count_distinct
- percentile
- first_value
- latest_value
- retention
- max
- min
- ''
description: >-
Aggregation type for numerator; Allowed:
count┃sum┃mean┃daily_participation┃ratio┃funnel┃count_distinct┃percentile.
valueColumn:
type: string
description: Column name representing the metric’s value.
winsorizationHigh:
type: number
maximum: 1
minimum: 0
description: High threshold for winsorization; must be between 0 and 1.
winsorizationLow:
type: number
maximum: 1
minimum: 0
description: Low threshold for winsorization; must be between 0 and 1.
cupedAttributionWindow:
type: number
nullable: true
description: Attribution window for CUPED adjustments in days.
onlyIncludeUsersWithConversionEvent:
type: boolean
description: >-
Flag to include only users with a conversion event in the
metric.
percentile:
type: number
description: Percentile value for statistical calculations.
valueThreshold:
type: number
description: Threshold value for filtering metrics.
cap:
type: number
description: Maximum cap for metric values.
rollupTimeWindow:
type: string
description: General time window for rollup; can specify custom settings.
customRollUpStart:
type: number
description: Custom start date for rollup in days since exposure.
customRollUpEnd:
type: number
description: Custom end date for rollup in days since exposure.
allowNullRatioDenominator:
type: boolean
description: >-
Include units which do not have a denominator. Only applicable
to ratios.
description: Defines warehouse native metrics for advanced configurations.
team:
type: string
nullable: true
description: >-
The team associated with the metric, applicable for enterprise
environments.
teamID:
type: string
nullable: true
description: >-
The team ID associated with the metric, applicable for enterprise
environments.
dryRun:
type: boolean
description: >-
Skips persisting the metric (used to validate that inputs are
correct)
id:
type: string
description: >-
Unique identifier for the metric, used for referencing within the
system.
example: metricId
isHidden:
type: boolean
description: Indicates if the metric is hidden from the user interface.
example: false
lineage:
type: object
properties:
events:
type: array
items:
type: string
description: List of event names that contribute to the metric’s calculation.
example:
- event1
- event2
metrics:
type: array
items:
type: string
description: List of metric names that are part of this metric’s lineage.
example:
- metric1
- metric2
required:
- events
- metrics
creatorName:
type: string
nullable: true
description: Name of the person who created the metric, if available.
example: creatorName
creatorEmail:
type: string
nullable: true
description: Email address of the metric creator for contact purposes.
example: creatorEmail
createdTime:
type: number
description: Timestamp indicating when the metric was created.
example: 1716230400
lastModifierID:
type: string
nullable: true
description: ID of the last modifier.
lastModifiedTime:
type: number
nullable: true
description: Time of the last modification to this metric.
lastModifierEmail:
type: string
nullable: true
description: Email of the last modifier.
lastModifierName:
type: string
nullable: true
description: Name of the last modifier.
owner:
type: object
properties:
name:
type: string
description: Name of the owner responsible for the metric’s management.
example: ownerName
required:
- name
required:
- name
- type
- directionality
- id
- lineage
securitySchemes:
STATSIG-API-KEY:
type: apiKey
name: STATSIG-API-KEY
in: header
````