Metrics

Metrics track flag behavior over time when an experiment is running. The data generated from experiments gives you more insight into the impact of a particular flag. To learn more, read Metrics.

Using the metrics API, you can create, delete, and manage metrics.

Are you importing metric events?

If you want to import metric events into LaunchDarkly from an existing data source, use the metric import API. To learn more, read Importing metric events.

Metric keys and event keys are different

LaunchDarkly automatically generates a metric key when you create a metric. You can use the metric key to identify the metric in API calls.

Custom conversion/binary and custom numeric metrics also require an event key. You can set the event key to anything you want. Adding this event key to your codebase lets your SDK track actions customers take in your app as events. To learn more, read Sending custom events.

List metrics

Get a list of all metrics for the specified project.

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.

Request
path Parameters
projectKey
required
string <string>

The project key

query Parameters
expand
string <string>

A comma-separated list of properties that can reveal additional information in the response.

limit
integer <int64>

The number of metrics to return in the response. Defaults to 20. Maximum limit is 50.

offset
integer <int64>

Where to start in the list. Use this with pagination. For example, an offset of 10 skips the first ten items and returns the next limit items.

sort
string <string>

A field to sort the items by. Prefix field by a dash ( - ) to sort in descending order. This endpoint supports sorting by createdAt or name.

Responses
200

Metrics collection response

401

Invalid access token

404

Invalid resource identifier

get/api/v2/metrics/{projectKey}
Request samples 
Response samples 
application/json
{
  • "items": [
    ],
  • "_links": {
    },
  • "totalCount": 0
}
Create metric
Create a new metric in the specified project. The expected POST body differs depending on the specified kind property.


Request 
path Parameters
projectKey
required
string <string> 
The project key


 
Request Body schema: application/json
required
key
required
string
A unique key to reference the metric


 
name
string
A human-friendly name for the metric


 
description
string
Description of the metric


 
kind
required
string
The kind of event your metric will track


 Enum: "pageview" "click" "custom"  
selector
string
One or more CSS selectors. Required for click metrics only.


 
Array of objects (UrlPost) 
One or more target URLs. Required for click and pageview metrics only.


 
isActive
boolean
Whether the metric is active. Set to true to record click or pageview metrics. Not applicable for custom metrics.


 
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 metrics only.


 
unit
string
The unit of measure. Applicable for numeric custom 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 numeric metrics, optional for custom conversion metrics.


 Enum: "HigherThanBaseline" "LowerThanBaseline"  
tags
Array of strings
Tags for the metric


 
randomizationUnits
Array of strings
An array of randomization units allowed for this metric


 
unitAggregationType
string
The method by which multiple unit event values are aggregated


 Enum: "average" "sum"  
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.


 
object (MetricEventDefaultRep) 
 
Responses 
201
Metric response


400
Invalid request


401
Invalid access token


403
Forbidden


404
Invalid resource identifier


409
Status conflict


429
Rate limited


post/api/v2/metrics/{projectKey}
Request samples 
application/json
{
  • "eventKey": "trackedClick",
  • "isActive": true,
  • "isNumeric": false,
  • "key": "metric-key-123abc",
  • "kind": "custom"
}
Response samples 
application/json
{
  • "experimentCount": 0,
  • "metricGroupCount": 0,
  • "_id": "5902deadbeef667524a01290",
  • "_versionId": "version-id-123abc",
  • "key": "metric-key-123abc",
  • "name": "My metric",
  • "kind": "custom",
  • "_attachedFlagCount": 0,
  • "_links": {
    },
  • "_site": {
    },
  • "_access": {
    },
  • "tags": [ ],
  • "_creationDate": 0,
  • "lastModified": {
    },
  • "maintainerId": "569fdeadbeef1644facecafe",
  • "_maintainer": {
    },
  • "description": "string",
  • "isNumeric": true,
  • "successCriteria": "HigherThanBaseline",
  • "unit": "string",
  • "eventKey": "string",
  • "randomizationUnits": [
    ],
  • "unitAggregationType": "average",
  • "analysisType": "mean",
  • "percentileValue": 95,
  • "eventDefault": {
    },
  • "experiments": [
    ],
  • "metricGroups": [
    ],
  • "isActive": true,
  • "_attachedFeatures": [
    ],
  • "_version": 1,
  • "selector": "string",
  • "urls": [
    ]
}
Get metric
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.


Request 
path Parameters
projectKey
required
string <string> 
The project key


 
metricKey
required
string <string> 
The metric key


 
query Parameters
expand
string <string> 
A comma-separated list of properties that can reveal additional information in the response.


 
versionId
string <string> 
The specific version ID of the metric


 
Responses 
200
Metric response


401
Invalid access token


403
Forbidden


404
Invalid resource identifier


429
Rate limited


get/api/v2/metrics/{projectKey}/{metricKey}
Request samples 
Response samples 
application/json
{
  • "experimentCount": 0,
  • "metricGroupCount": 0,
  • "_id": "5902deadbeef667524a01290",
  • "_versionId": "version-id-123abc",
  • "key": "metric-key-123abc",
  • "name": "My metric",
  • "kind": "custom",
  • "_attachedFlagCount": 0,
  • "_links": {
    },
  • "_site": {
    },
  • "_access": {
    },
  • "tags": [ ],
  • "_creationDate": 0,
  • "lastModified": {
    },
  • "maintainerId": "569fdeadbeef1644facecafe",
  • "_maintainer": {
    },
  • "description": "string",
  • "isNumeric": true,
  • "successCriteria": "HigherThanBaseline",
  • "unit": "string",
  • "eventKey": "string",
  • "randomizationUnits": [
    ],
  • "unitAggregationType": "average",
  • "analysisType": "mean",
  • "percentileValue": 95,
  • "eventDefault": {
    },
  • "experiments": [
    ],
  • "metricGroups": [
    ],
  • "isActive": true,
  • "_attachedFeatures": [
    ],
  • "_version": 1,
  • "selector": "string",
  • "urls": [
    ]
}
Update metric
Patch a metric by key. Updating a metric uses a JSON patch representation of the desired changes. To learn more, read Updates.


Request 
path Parameters
projectKey
required
string <string> 
The project key


 
metricKey
required
string <string> 
The metric key


 
Request Body schema: application/json
required
 Array 
op
required
string
The type of operation to perform


 
path
required
string
A JSON Pointer string specifying the part of the document to operate on


 
value
any
A JSON value used in "add", "replace", and "test" operations


 
Responses 
200
Metric response


400
Invalid request


401
Invalid access token


404
Invalid resource identifier


409
Status conflict


429
Rate limited


patch/api/v2/metrics/{projectKey}/{metricKey}
Request samples 
application/json
[
  • {
    }
]
Response samples 
application/json
{
  • "experimentCount": 0,
  • "metricGroupCount": 0,
  • "_id": "5902deadbeef667524a01290",
  • "_versionId": "version-id-123abc",
  • "key": "metric-key-123abc",
  • "name": "My metric",
  • "kind": "custom",
  • "_attachedFlagCount": 0,
  • "_links": {
    },
  • "_site": {
    },
  • "_access": {
    },
  • "tags": [ ],
  • "_creationDate": 0,
  • "lastModified": {
    },
  • "maintainerId": "569fdeadbeef1644facecafe",
  • "_maintainer": {
    },
  • "description": "string",
  • "isNumeric": true,
  • "successCriteria": "HigherThanBaseline",
  • "unit": "string",
  • "eventKey": "string",
  • "randomizationUnits": [
    ],
  • "unitAggregationType": "average",
  • "analysisType": "mean",
  • "percentileValue": 95,
  • "eventDefault": {
    },
  • "experiments": [
    ],
  • "metricGroups": [
    ],
  • "isActive": true,
  • "_attachedFeatures": [
    ],
  • "_version": 1,
  • "selector": "string",
  • "urls": [
    ]
}
Delete metric
Delete a metric by key.


Request 
path Parameters
projectKey
required
string <string> 
The project key


 
metricKey
required
string <string> 
The metric key


 
Responses 
204
Action succeeded


401
Invalid access token


403
Forbidden


404
Invalid resource identifier


429
Rate limited


delete/api/v2/metrics/{projectKey}/{metricKey}
Request samples 
Response samples 
application/json
{
  • "code": "unauthorized",
  • "message": "Invalid access token"
}
➔ Next to Metrics (beta)