LaunchDarkly REST API
LaunchDarkly DocsSign in
HomeAPI ReferenceSDKsContext Plugin
Metrics

Create metric

POST
/api/v2/metrics/{projectKey}

Create a new metric in the specified project. The expected POST body differs depending on the specified kind property.

Authorization

ApiKey read, write
Authorization<token>

In: header

Scope: read, write

Path Parameters

projectKey*string

The project key

Formatstring

Request Body

application/json

key*string

A unique key to reference the metric

name?string

A human-friendly name for the metric

description?string

Description of the metric

kind*string

The kind of event your metric will track

Value in

  • "pageview"
  • "click"
  • "custom"
  • "trace"
selector?string

One or more CSS selectors. Required for click metrics only.

urls?array<>

One or more target URLs. Required for click and pageview metrics only.

isNumeric?boolean

Whether to track numeric changes in value against a baseline (true) or to track a conversion when an end user takes an action (false). Required for custom and trace metrics only.

unit?string

The unit of measure. Applicable for numeric custom and trace metrics only.

eventKey?string

The event key to use in your code. Required for custom conversion/binary and custom numeric metrics only.

successCriteria?string

Success criteria. Required for custom and trace numeric metrics, optional for custom and trace conversion metrics.

Value in

  • "HigherThanBaseline"
  • "LowerThanBaseline"
tags?array<string>

Tags for the metric

randomizationUnits?array<string>
Deprecated

Deprecated, use analysisUnits instead.

analysisUnits?array<string>

An array of analysis units allowed for this metric.

maintainerId?string

The ID of the member who maintains this metric

unitAggregationType?string

The method by which multiple unit event values are aggregated

Value in

  • "average"
  • "sum"
  • "count_distinct"
analysisType?string

The method for analyzing metric events

percentileValue?integer

The percentile for the analysis method. An integer denoting the target percentile between 0 and 100. Required when analysisType is percentile.

eventDefault?
dataSource?
filters?

Filters for the metric to exclude certain events from being included. This is only supported for custom metrics.

windowStartOffset?integer

Not yet implemented - The start of the measurement window, in milliseconds relative to the unit's first exposure to a flag variation

Formatint64
windowEndOffset?integer

Not yet implemented - The end of the measurement window, in milliseconds relative to the unit's first exposure to a flag variation

Formatint64
winsorLowerPercentile?number

Lower winsorization percentile, expressed as a percent in the open interval (0, 100). When both bounds are set, defines a two-sided clamp range. Otherwise lower-only winsorization.

winsorUpperPercentile?number

Upper winsorization percentile, expressed as a percent in the open interval (0, 100). When both bounds are set, must be greater than winsorLowerPercentile.

winsorIncludeImputed?boolean

When true, the percentile bound calculation includes imputed zeros. Only meaningful when at least one bound is set and the metric includes units that didn't send events.

traceQuery?string

The trace query to use for the metric. Required for trace metrics.

traceValueLocation?string

The location in the trace to use for numeric values. Required for numeric trace metrics.

unitAggregationField?string

The warehouse column to use for counting distinct values. Required when the unitAggregationType is count_distinct.

valueColumn?string

For numeric warehouse-native metrics, the column holding the numeric value. Overrides the value column mapped on the data source.

denominator?

For ratio metrics, the denominator event configuration. Only supported for warehouse native custom metrics.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/api/v2/metrics/string" \  -H "Content-Type: application/json" \  -d '{    "eventKey": "Order placed",    "isNumeric": false,    "key": "metric-key-123abc",    "kind": "custom"  }'
{  "experimentCount": 0,  "metricGroupCount": 0,  "activeExperimentCount": 2,  "activeGuardedRolloutCount": 1,  "_id": "5902deadbeef667524a01290",  "_versionId": "version-id-123abc",  "_version": 1,  "key": "metric-key-123abc",  "name": "My metric",  "kind": "custom",  "_attachedFlagCount": 0,  "_links": {    "parent": {      "href": "/api/v2/metrics/my-project",      "type": "application/json"    },    "self": {      "href": "/api/v2/metrics/my-project/my-metric",      "type": "application/json"    }  },  "_site": "{\"href\":\"/my-project/metrics/my-metric/details\",\"type\":\"text/html\"}",  "_access": {    "denied": [      {        "action": "string",        "reason": {          "resources": [            "proj/*:env/*;qa_*:/flag/*"          ],          "notResources": [            "string"          ],          "actions": [            "*"          ],          "notActions": [            "string"          ],          "effect": "allow",          "role_name": "string"        }      }    ],    "allowed": [      {        "action": "string",        "reason": {          "resources": [            "proj/*:env/*;qa_*:/flag/*"          ],          "notResources": [            "string"          ],          "actions": [            "*"          ],          "notActions": [            "string"          ],          "effect": "allow",          "role_name": "string"        }      }    ]  },  "tags": [],  "_creationDate": "1628192791148",  "lastModified": {    "date": "2021-08-05T19:46:31.148082Z"  },  "maintainerId": "569fdeadbeef1644facecafe",  "_maintainer": "{\"_links\":{\"self\":{\"href\":\"/api/v2/members/569fdeadbeef1644facecafe\",\"type\":\"application/json\"}},\"_id\":\"569fdeadbeef1644facecafe\",\"firstName\":\"Ariel\",\"lastName\":\"Flores\",\"role\":\"owner\",\"email\":\"ariel@acme.com\"}",  "description": "string",  "category": "Error monitoring",  "isNumeric": true,  "successCriteria": "HigherThanBaseline",  "unit": "string",  "eventKey": "Order placed",  "randomizationUnits": [    "user"  ],  "analysisUnits": [    "user"  ],  "filters": "{\"type\":\"group\",\"op\":\"and\",\"values\":[{\"type\":\"contextAttribute\",\"op\":\"in\",\"contextKind\":\"user\",\"attribute\":\"country\",\"values\":[\"JP\"],\"negate\":false},{\"type\":\"eventProperty\",\"op\":\"in\",\"attribute\":\"category\",\"values\":[\"magic-wands\"],\"negate\":false}]}",  "unitAggregationType": "average",  "analysisType": "mean",  "percentileValue": 95,  "eventDefault": {    "disabled": true,    "value": 0  },  "dataSource": {    "key": "string",    "environmentKey": "string",    "_name": "string",    "_integrationKey": "string"  },  "lastSeen": 0,  "archived": true,  "archivedAt": "1609459200000",  "selector": "string",  "urls": "[{\"kind\":\"exact\",\"url\":\"https://www.example.com/page1\"}]",  "windowStartOffset": 0,  "windowEndOffset": 0,  "winsorLowerPercentile": 1,  "winsorUpperPercentile": 99.5,  "winsorIncludeImputed": false,  "traceQuery": "service.name = \"checkout\"",  "traceValueLocation": "duration",  "unitAggregationField": "string",  "denominator": {    "eventName": "string",    "isNumeric": true,    "unitAggregationType": "string",    "unitAggregationField": "string",    "valueColumn": "string",    "dataSource": {      "key": "string",      "environmentKey": "string",      "_name": "string",      "_integrationKey": "string"    },    "filters": {      "type": "contextAttribute",      "attribute": "country",      "op": "in",      "values": [        "JP"      ],      "contextKind": "user",      "negate": false    },    "windowStartOffset": 0,    "windowEndOffset": 0,    "winsorLowerPercentile": 0,    "winsorUpperPercentile": 0,    "winsorIncludeImputed": true  },  "experiments": [    {      "key": "experiment-key-123abc",      "name": "Example experiment",      "environmentId": "1234a56b7c89d012345e678f",      "environmentKey": "production",      "creationDate": "1654104600000",      "archivedDate": "1654104600000",      "_links": {        "parent": {          "href": "/api/v2/projects/my-project/environments/my-environment",          "type": "application/json"        },        "self": {          "href": "/api/v2/projects/my-project/environments/my-environment/experiments/example-experiment",          "type": "application/json"        }      }    }  ],  "metricGroups": [    {      "key": "metric-group-key-123abc",      "name": "My metric group",      "kind": "funnel",      "_links": {        "parent": {          "href": "/api/v2/projects/my-project",          "type": "application/json"        },        "self": {          "href": "/api/v2/projects/my-project/metric-groups/my-metric-group",          "type": "application/json"        }      }    }  ],  "lastUsedInExperiment": {    "key": "experiment-key-123abc",    "name": "Example experiment",    "environmentId": "1234a56b7c89d012345e678f",    "environmentKey": "production",    "creationDate": "1654104600000",    "archivedDate": "1654104600000",    "_links": {      "parent": {        "href": "/api/v2/projects/my-project/environments/my-environment",        "type": "application/json"      },      "self": {        "href": "/api/v2/projects/my-project/environments/my-environment/experiments/example-experiment",        "type": "application/json"      }    }  },  "lastUsedInGuardedRollout": {    "_id": "885ccadf-181b-4a9a-8414-7ad6f7ba2db0",    "flagKey": "my-flag",    "flagName": "My Flag",    "flagPurpose": "migration",    "environmentKey": "production",    "environmentName": "Production",    "status": "monitoring",    "creationDate": "1654104600000",    "_links": {      "self": {        "href": "/internal/projects/my-project/environments/production/automated-releases/885ccadf-181b-4a9a-8414-7ad6f7ba2db0",        "type": "application/json"      }    }  },  "isActive": true,  "_attachedFeatures": [    {      "name": "Example flag",      "key": "flag-key-123abc",      "_links": {        "property1": {          "href": "string",          "type": "string"        },        "property2": {          "href": "string",          "type": "string"        }      },      "_site": {        "href": "string",        "type": "string"      }    }  ]}

List metrics GET

Get a list of all metrics for the specified project. ### Filtering metrics The `filter` parameter supports the following operators: `contains`, `equals`, `anyOf`. #### Supported fields and operators You can only filter certain fields in metrics when using the `filter` parameter. Additionally, you can only filter some fields with certain operators. When you search for metrics, the `filter` parameter supports the following fields and operators: |<div style="width:120px">Field</div> |Description |Supported operators | |---|---|---| | `dataSourceKeys` | The data source that provides events for this metric (for example, "launchdarkly-hosted"). | `anyOf`, `notEquals` | | `eventKeys` | The metric event key. | `anyOf` | | `eventKind` | The metric event kind. One of `custom`, `pageview`, `click`. | `equals` | | `hasConnections` | Whether the metric has connections to experiments or guarded rollouts. One of `true`, `false`. | `equals` | | `isNumeric` | Whether the metric is numeric. One of `true`, `false`. | `equals` | | `maintainerIds` | A comma-separated list of metric maintainer IDs. | `anyOf` | | `maintainerTeamKey` | The metric maintainer team key. | `equals` | | `metricUsedIn` | Filter by where the metric is used. One of `experiments`, `guarded_rollouts`, `any`, `none`. | `equals` | | `query` | A "fuzzy" search across metric key and name. Supply a string or list of strings to the operator. | `equals` | | `tags` | The metric tags. | `contains` | | `unitAggregationType` | The metric's unit aggregation type. One of `sum`, `average`. | `equals` | | `versionIds` | The metric version number. | `anyOf` | | `view` | The view used to restrict access to the metric. | `equals` | For example, the filter `?filter=tags contains ["tag1", "tag2", "tag3"]` matches metrics that have all three tags. The documented values for `filter` query parameters are prior to URL encoding. For example, the `[` in `?filter=tags contains ["tag1", "tag2", "tag3"]` must be encoded to `%5B`. ### Expanding the metric list response LaunchDarkly supports expanding the "List metrics" response. By default, the expandable field is **not** included in the response. To expand the response, append the `expand` query parameter and add the following supported field: - `experimentCount` includes the number of experiments from the specific project that use the metric For example, `expand=experimentCount` includes the `experimentCount` field for each metric in the response.

Get metric GET

Get information for a single metric from the specific project. ### Expanding the metric response LaunchDarkly supports four fields for expanding the "Get metric" response. By default, these fields are **not** included in the response. To expand the response, append the `expand` query parameter and add a comma-separated list with any of the following fields: - `experiments` includes all experiments from the specific project that use the metric - `experimentCount` includes the number of experiments from the specific project that use the metric - `metricGroups` includes all metric groups from the specific project that use the metric - `metricGroupCount` includes the number of metric groups from the specific project that use the metric For example, `expand=experiments` includes the `experiments` field in the response.