Skip to main content
POST
/
console
/
v1
/
metrics
Create Metric
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",
        "column": "<string>",
        "condition": "in",
        "values": [
          "<string>"
        ],
        "nullVacuousOverride": true
      }
    ],
    "waitForCohortWindow": true,
    "denominatorCriteria": [
      {
        "type": "value",
        "column": "<string>",
        "condition": "in",
        "values": [
          "<string>"
        ],
        "nullVacuousOverride": true
      }
    ],
    "denominatorAggregation": "count",
    "denominatorCustomRollupEnd": 123,
    "denominatorCustomRollupStart": 123,
    "denominatorMetricSourceName": "<string>",
    "denominatorRollupTimeWindow": "<string>",
    "denominatorValueColumn": "<string>",
    "funnelCalculationWindow": 123,
    "funnelCountDistinct": "sessions",
    "funnelEvents": [
      {
        "criteria": [
          {
            "type": "value",
            "column": "<string>",
            "condition": "in",
            "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": "owner123@test.com"
    },
    "lineage": {
      "events": [
        "add_to_cart"
      ],
      "metrics": []
    },
    "team": "Console Team",
    "unitTypes": [
      "userID"
    ],
    "metricEvents": [
      {
        "name": "add_to_cart",
        "type": "metadata",
        "criteria": []
      }
    ]
  }
}

Authorizations

​
STATSIG-API-KEY
string
header
required

Headers

​
x-respect-review-settings
string

Optional header to respect review settings for mutation endpoints.

Body

application/json
​
name
string
required

The name of the new metric, which identifies it within the system.

Required string length: 4 - 200
Example:

"metricName"

​
type
enum<string>
required
Available options:
ratio,
mean,
event_count_custom,
event_user,
funnel,
composite,
composite_sum,
sum,
undefined,
user_warehouse
Example:

"sum"

​
isVerified
boolean

Marks the metric as verified for internal trustworthiness.

Example:

false

​
isReadOnly
boolean

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

Example:

false

​
unitTypes
string[]

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

Example:
["stableID", "userID"]
​
metricEvents
object[]

An array of event definitions used to compute the metric.

Example:
[{ "name": "event1", "type": "value" }]
​
metricComponentMetrics
object[]

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

Example:
[]
​
description
string

A description of the new metric, providing context and purpose.

Maximum length: 1000
​
directionality
enum<string>
default:increase

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

Available options:
increase,
decrease
Example:

"increase"

​
tags

Tags associated with the metric for categorization and searchability.

Example:
["tag1", "tag2"]
​
isPermanent
boolean

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

Example:

false

​
rollupTimeWindow
string

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

Example:

"custom"

​
customRollUpStart
number

Custom time window start date in days since exposure.

Example:

1

​
customRollUpEnd
number

Custom time window end date in days since exposure.

Example:

1

​
funnelEventList
object[]

List of events used to create funnel metrics.

​
funnelCountDistinct
enum<string>

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

Available options:
events,
users
​
warehouseNative
object

Defines warehouse native metrics for advanced configurations.

​
team
string | null

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

​
teamID
string | null

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

​
dryRun
boolean

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

Response

Create metric response

​
message
string
required

A simple string explaining the result of the operation.

​
data
object
required

A single result.

⌘I