Create metric

For the complete documentation index, see llms.txt. For the full documentation snapshot, see llms-full.txt.

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

POST /api/v2/metrics/{projectKey}

Create metric

cURL

curl --request POST \
  --url https://app.launchdarkly.com/api/v2/metrics/{projectKey} \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "eventKey": "Order placed",
  "isNumeric": false,
  "key": "metric-key-123abc",
  "kind": "custom"
}
'

201

{
  "_id": "5902deadbeef667524a01290",
  "_versionId": "version-id-123abc",
  "key": "metric-key-123abc",
  "name": "My metric",
  "kind": "custom",
  "_links": {
    "parent": {
      "href": "/api/v2/metrics/my-project",
      "type": "application/json"
    },
    "self": {
      "href": "/api/v2/metrics/my-project/my-metric",
      "type": "application/json"
    }
  },
  "tags": [],
  "_creationDate": "1628192791148",
  "dataSource": {
    "key": "<string>",
    "environmentKey": "<string>",
    "_name": "<string>",
    "_integrationKey": "<string>"
  },
  "experimentCount": 0,
  "metricGroupCount": 0,
  "activeExperimentCount": 2,
  "activeGuardedRolloutCount": 1,
  "_version": 1,
  "_attachedFlagCount": 0,
  "_site": "{\"href\":\"/experiments/metrics/my-metric/edit\",\"type\":\"text/html\"}",
  "_access": {
    "denied": [
      {
        "action": "<string>",
        "reason": {
          "effect": "allow",
          "resources": [
            "proj/*:env/*;qa_*:/flag/*"
          ],
          "notResources": [
            "<string>"
          ],
          "actions": [
            "*"
          ],
          "notActions": [
            "<string>"
          ],
          "role_name": "<string>"
        }
      }
    ],
    "allowed": [
      {
        "action": "<string>",
        "reason": {
          "effect": "allow",
          "resources": [
            "proj/*:env/*;qa_*:/flag/*"
          ],
          "notResources": [
            "<string>"
          ],
          "actions": [
            "*"
          ],
          "notActions": [
            "<string>"
          ],
          "role_name": "<string>"
        }
      }
    ]
  },
  "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\":\"[e-mail]\"}",
  "description": "<string>",
  "category": "Error monitoring",
  "isNumeric": true,
  "successCriteria": "HigherThanBaseline",
  "unit": "<string>",
  "eventKey": "Order placed",
  "randomizationUnits": [
    "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
  },
  "lastSeen": 123,
  "archived": true,
  "archivedAt": "1609459200000",
  "selector": "<string>",
  "urls": "[{\"kind\":\"exact\",\"url\":\"https://www.example.com/page1\"}]",
  "windowStartOffset": 123,
  "windowEndOffset": 123,
  "traceQuery": "service.name = \"checkout\"",
  "traceValueLocation": "duration",
  "experiments": [
    {
      "key": "experiment-key-123abc",
      "name": "Example experiment",
      "environmentId": "1234a56b7c89d012345e678f",
      "environmentKey": "production",
      "creationDate": "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"
        }
      },
      "archivedDate": "1654104600000"
    }
  ],
  "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",
    "_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"
      }
    },
    "archivedDate": "1654104600000"
  },
  "lastUsedInGuardedRollout": {
    "_id": "885ccadf-181b-4a9a-8414-7ad6f7ba2db0",
    "flagKey": "my-flag",
    "flagName": "My Flag",
    "environmentKey": "production",
    "environmentName": "Production",
    "status": "monitoring",
    "creationDate": "1654104600000",
    "_links": {
      "self": {
        "href": "/api/v2/projects/my-project/flags/my-flag/environments/production/measured-rollouts/885ccadf-181b-4a9a-8414-7ad6f7ba2db0",
        "type": "application/json"
      }
    },
    "flagPurpose": "migration"
  },
  "isActive": true,
  "_attachedFeatures": [
    {
      "name": "Example flag",
      "key": "flag-key-123abc",
      "_links": {},
      "_site": {
        "href": "<string>",
        "type": "<string>"
      }
    }
  ]
}

Authorizations

Authorization · string · header · required

Path Parameters

projectKey · string<string> · required

The project key

Body

application/json

key · string · required

A unique key to reference the metric

Example:

"metric-key-123abc"

kind · enum<string> · required

The kind of event your metric will track

Available options: pageview, click, custom, trace

Example:

"custom"

name · string

A human-friendly name for the metric

Example:

"Example metric"

description · string

Description of the metric

Example:

"optional description"

selector · string

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

Example:

".dropdown-toggle"

urls · object[]

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

Show child attributes

Example:

"invalid example"

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.

Example:

false

unit · string

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

Example:

"orders"

eventKey · string

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

Example:

"Order placed"

successCriteria · enum<string>

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

Available options: HigherThanBaseline, LowerThanBaseline

Example:

"HigherThanBaseline"

tags · string[]

Tags for the metric

Example:

["example-tag"]

randomizationUnits · string[]

An array of randomization units allowed for this metric

Example:

["user"]

maintainerId · string

The ID of the member who maintains this metric

Example:

"569fdeadbeef1644facecafe"

unitAggregationType · enum<string>

The method by which multiple unit event values are aggregated

Available options: average, sum

Example:

"average"

analysisType · string

The method for analyzing metric events

Example:

"mean"

percentileValue · integer

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

Example:

95

eventDefault · object

Show child attributes

dataSource · object

Show child attributes

filters · object

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

Show child attributes

windowStartOffset · integer<int64>

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

windowEndOffset · integer<int64>

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

traceQuery · string

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

Example:

"service.name = \"checkout\""

traceValueLocation · string

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

Example:

"duration"

Response

201

application/json

Metric response

_id · string · required

The ID of this metric

Example:

"5902deadbeef667524a01290"

_versionId · string · required

The version ID of the metric

Example:

"version-id-123abc"

key · string · required

A unique key to reference the metric

Example:

"metric-key-123abc"

name · string · required

A human-friendly name for the metric

Example:

"My metric"

kind · enum<string> · required

The kind of event the metric tracks

Available options: pageview, click, custom, trace

Example:

"custom"

_links · object · required

The location and content type of related resources

Show child attributes

Example:

{
  "parent": {
    "href": "/api/v2/metrics/my-project",
    "type": "application/json"
  },
  "self": {
    "href": "/api/v2/metrics/my-project/my-metric",
    "type": "application/json"
  }
}

tags · string[] · required

Tags for the metric

Example:

[]

_creationDate · integer<int64> · required

Timestamp of when the metric was created

Example:

"1628192791148"

dataSource · object · required

Show child attributes

experimentCount · integer

The number of experiments using this metric

Example:

0

metricGroupCount · integer

The number of metric groups using this metric

Example:

0

activeExperimentCount · integer

The number of active experiments using this metric

Example:

2

activeGuardedRolloutCount · integer

The number of active guarded rollouts using this metric

Example:

1

_version · integer

Version of the metric

Example:

1

_attachedFlagCount · integer

The number of feature flags currently attached to this metric

Example:

0

_site · object

Details on how to access the metric in the LaunchDarkly UI

Show child attributes

Example:

"{\"href\":\"/experiments/metrics/my-metric/edit\",\"type\":\"text/html\"}"

_access · object

Details on the allowed and denied actions for this metric

Show child attributes

lastModified · object

Show child attributes

maintainerId · string

The ID of the member who maintains this metric

Example:

"569fdeadbeef1644facecafe"

_maintainer · object

Details on the member who maintains this metric

Show child attributes

Example:

"{\"_links\":{\"self\":{\"href\":\"/api/v2/members/569fdeadbeef1644facecafe\",\"type\":\"application/json\"}},\"_id\":\"569fdeadbeef1644facecafe\",\"firstName\":\"Ariel\",\"lastName\":\"Flores\",\"role\":\"owner\",\"email\":\"[e-mail]\"}"

description · string

Description of the metric

category · string

The category of the metric

Example:

"Error monitoring"

isNumeric · boolean

For custom and trace metrics, whether to track numeric changes in value against a baseline (true) or to track a conversion when an end user takes an action (false).

Example:

true

successCriteria · enum<string>

For custom and trace metrics, the success criteria

Available options: HigherThanBaseline, LowerThanBaseline

unit · string

For numeric custom and trace metrics, the unit of measure

eventKey · string

For custom metrics, the event key to use in your code

Example:

"Order placed"

randomizationUnits · string[]

An array of randomization units allowed for this metric

Example:

["user"]

filters · object

The filters narrowing down the audience based on context attributes or event properties.

Show child attributes

Example:

"{\"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 · enum<string>

The method by which multiple unit event values are aggregated

Available options: average, sum

Example:

"average"

analysisType · enum<string>

The method for analyzing metric events

Available options: mean, percentile

Example:

"mean"

percentileValue · integer

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

Example:

95

eventDefault · object

Show child attributes

lastSeen · integer<int64>

Timestamp of most recent data for this metric, at one-hour fidelity

archived · boolean

Whether the metric version is archived

archivedAt · integer<int64>

Timestamp when the metric version was archived

Example:

"1609459200000"

selector · string

For click metrics, the CSS selectors

urls · object[]

For click and pageview metrics, the target URLs

Show child attributes

Example:

"[{\"kind\":\"exact\",\"url\":\"https://www.example.com/page1\"}]"

windowStartOffset · integer<int64>

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

windowEndOffset · integer<int64>

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

traceQuery · string

For trace metrics, the trace query to use for the metric.

Example:

"service.name = \"checkout\""

traceValueLocation · string

For trace metrics, the location in the trace to use for numeric values.

Example:

"duration"

experiments · object[]

Experiments that use this metric, including those using a metric group that contains this metric

Show child attributes

metricGroups · object[]

Metric groups that use this metric

Show child attributes

lastUsedInExperiment · object

The most recent experiment that used this metric

Show child attributes

lastUsedInGuardedRollout · object

The most recent guarded rollout that used this metric

Show child attributes

isActive · boolean

Whether the metric is active

Example:

true

_attachedFeatures · object[]

Details on the flags attached to this metric

Show child attributes