Create a single fact metric

POST /fact-metrics

cURL

cURL

curl -X POST https://api.growthbook.io/api/v1/fact-metrics \
  -d '{"name":"Purchased", "metricType":"proportion", "numerator":{"factTableId":"ftb_abc123","column":"$$distinctUsers","filters":[]}}' \
  -u secret_abc123DEF456:

200

{
  "factMetric": {
    "id": "<string>",
    "name": "<string>",
    "description": "<string>",
    "owner": "<unknown>",
    "projects": [
      "<string>"
    ],
    "tags": [
      "<string>"
    ],
    "datasource": "<string>",
    "metricType": "proportion",
    "numerator": {
      "factTableId": "<string>",
      "column": "<string>",
      "aggregation": "sum",
      "filters": [
        "<string>"
      ],
      "inlineFilters": {},
      "rowFilters": [
        {
          "operator": "=",
          "values": [
            "<string>"
          ],
          "column": "<string>"
        }
      ],
      "aggregateFilterColumn": "<string>",
      "aggregateFilter": "<string>"
    },
    "inverse": true,
    "cappingSettings": {
      "type": "none",
      "value": 123,
      "ignoreZeros": true
    },
    "windowSettings": {
      "type": "none",
      "delayValue": 123,
      "delayUnit": "minutes",
      "windowValue": 123,
      "windowUnit": "minutes"
    },
    "regressionAdjustmentSettings": {
      "override": true,
      "enabled": true,
      "days": 123
    },
    "riskThresholdSuccess": 123,
    "riskThresholdDanger": 123,
    "minPercentChange": 123,
    "maxPercentChange": 123,
    "minSampleSize": 123,
    "targetMDE": 123,
    "managedBy": "",
    "dateCreated": "2023-11-07T05:31:56Z",
    "dateUpdated": "2023-11-07T05:31:56Z",
    "denominator": {
      "factTableId": "<string>",
      "column": "<string>",
      "filters": [
        "<string>"
      ],
      "inlineFilters": {},
      "rowFilters": [
        {
          "operator": "=",
          "values": [
            "<string>"
          ],
          "column": "<string>"
        }
      ]
    },
    "quantileSettings": {
      "type": "event",
      "ignoreZeros": true,
      "quantile": 0.5
    },
    "displayAsPercentage": true,
    "archived": true,
    "metricAutoSlices": [
      "<string>"
    ]
  }
}

Authorizations

bearerAuthbasicAuth

Authorization · string · header · required

If using Bearer auth, pass the Secret Key as the token:

curl https://api.growthbook.io/api/v1 \
  -H "Authorization: Bearer secret_abc123DEF456"

Body

application/json

name · string · required

metricType · enum<string> · required

Available options: proportion, retention, mean, quantile, ratio, dailyParticipation

numerator · object · required

Show child attributes

description · string

owner · any

projects · string[]

tags · string[]

denominator · object

Only when metricType is 'ratio'

Show child attributes

inverse · boolean

Set to true for things like Bounce Rate, where you want the metric to decrease

quantileSettings · object

Controls the settings for quantile metrics (mandatory if metricType is "quantile")

Show child attributes

cappingSettings · object

Controls how outliers are handled

Show child attributes

windowSettings · object

Controls the conversion window for the metric

Show child attributes

priorSettings · object

Controls the bayesian prior for the metric. If omitted, organization defaults will be used.

Show child attributes

regressionAdjustmentSettings · object

Controls the regression adjustment (CUPED) settings for the metric

Show child attributes

riskThresholdSuccess · number · deprecated

No longer used. Threshold for Risk to be considered low enough, as a proportion (e.g. put 0.0025 for 0.25%).
Must be a non-negative number and must not be higher than riskThresholdDanger.

Required range: x >= 0

riskThresholdDanger · number · deprecated

No longer used. Threshold for Risk to be considered too high, as a proportion (e.g. put 0.0125 for 1.25%).
Must be a non-negative number.

Required range: x >= 0

displayAsPercentage · boolean

If true and the metric is a ratio or dailyParticipation metric, variation means will be displayed as a percentage. Defaults to true for dailyParticipation metrics and false for ratio metrics.

minPercentChange · number

Minimum percent change to consider uplift significant, as a proportion (e.g. put 0.005 for 0.5%)

Required range: x >= 0

maxPercentChange · number

Maximum percent change to consider uplift significant, as a proportion (e.g. put 0.5 for 50%)

Required range: x >= 0

minSampleSize · number

Required range: x >= 0

targetMDE · number

The percentage change that you want to reliably detect before ending an experiment, as a proportion (e.g. put 0.1 for 10%). This is used to estimate the "Days Left" for running experiments.

Required range: x >= 0

managedBy · enum<string>

Set this to "api" to disable editing in the GrowthBook UI

Available options: , api, admin

metricAutoSlices · string[]

Array of slice column names that will be automatically included in metric analysis. This is an enterprise feature.

Response

200 - application/json

Success

factMetric · object · required

Show child attributes