v5

latestOpenAPI 3.0.3Apache 2.0raw.githubusercontent.com2026-02-283466592.5 MB

Metrics

Create metric

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

post/api/v2/metrics/{projectKey}

Path parameters

projectKeystring string required

The project key

Request body

keystring required

A unique key to reference the metric

namestring

A human-friendly name for the metric

descriptionstring

Description of the metric

kind'pageview' | 'click' | 'custom' required

The kind of event your metric will track

selectorstring

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

isNumericboolean

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

unitstring

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

eventKeystring

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

successCriteria'HigherThanBaseline' | 'LowerThanBaseline'

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

tagsstring[]

Tags for the metric

randomizationUnitsstring[]

An array of randomization units allowed for this metric

maintainerIdstring

The ID of the member who maintains this metric

unitAggregationType'average' | 'sum'

The method by which multiple unit event values are aggregated

analysisTypestring

The method for analyzing metric events

percentileValueinteger

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

Example request

{
  "key": "metric-key-123abc",
  "name": "Example metric",
  "description": "optional description",
  "kind": "custom",
  "selector": ".dropdown-toggle",
  "unit": "orders",
  "eventKey": "Order placed",
  "successCriteria": "HigherThanBaseline",
  "tags": [
    "example-tag"
  ],
  "randomizationUnits": [
    "user"
  ],
  "maintainerId": "569fdeadbeef1644facecafe",
  "unitAggregationType": "average",
  "analysisType": "mean",
  "percentileValue": 95,
  "filters": {
    "type": "contextAttribute",
    "attribute": "country",
    "values": [
      "JP"
    ],
    "contextKind": "user"
  }
}

Response

Metric response

experimentCountinteger

The number of experiments using this metric

metricGroupCountinteger

The number of metric groups using this metric

activeExperimentCountinteger

The number of active experiments using this metric

activeGuardedRolloutCountinteger

The number of active guarded rollouts using this metric

_idstring required

The ID of this metric

_versionIdstring required

The version ID of the metric

_versioninteger

Version of the metric

keystring required

A unique key to reference the metric

namestring required

A human-friendly name for the metric

kind'pageview' | 'click' | 'custom' required

The kind of event the metric tracks

_attachedFlagCountinteger

The number of feature flags currently attached to this metric

_linksobject required

The location and content type of related resources

tagsstring[] required

Tags for the metric

_creationDateinteger required

maintainerIdstring

The ID of the member who maintains this metric

descriptionstring

Description of the metric

categorystring

The category of the metric

isNumericboolean

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

successCriteria'HigherThanBaseline' | 'LowerThanBaseline'

For custom metrics, the success criteria

unitstring

For numeric custom metrics, the unit of measure

eventKeystring

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

randomizationUnitsstring[]

An array of randomization units allowed for this metric

unitAggregationType'average' | 'sum'

The method by which multiple unit event values are aggregated

analysisType'mean' | 'percentile'

The method for analyzing metric events

percentileValueinteger

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

lastSeeninteger

archivedboolean

Whether the metric version is archived

archivedAtinteger

selectorstring

For click metrics, the CSS selectors

urlsUrlMatcher[]

isActiveboolean

Whether the metric is active

Example response

{
  "activeExperimentCount": 2,
  "activeGuardedRolloutCount": 1,
  "_id": "5902deadbeef667524a01290",
  "_versionId": "version-id-123abc",
  "_version": 1,
  "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"
    }
  },
  "_access": {
    "denied": [
      {
        "reason": {
          "resources": [
            "proj/*:env/*;qa_*:/flag/*"
          ],
          "actions": [
            "*"
          ],
          "effect": "allow"
        }
      }
    ],
    "allowed": [
      {
        "reason": {
          "resources": [
            "proj/*:env/*;qa_*:/flag/*"
          ],
          "actions": [
            "*"
          ],
          "effect": "allow"
        }
      }
    ]
  },
  "tags": [],
  "lastModified": {
    "date": "2021-08-05T19:46:31.148082Z"
  },
  "maintainerId": "569fdeadbeef1644facecafe",
  "_maintainer": {
    "_links": {
      "self": {
        "href": "/api/v2/members/569f183514f4432160000007",
        "type": "application/json"
      }
    },
    "_id": "569f183514f4432160000007",
    "firstName": "Ariel",
    "lastName": "Flores",
    "role": "admin",
    "email": "ariel@acme.com"
  },
  "category": "Error monitoring",
  "isNumeric": true,
  "eventKey": "Order placed",
  "randomizationUnits": [
    "user"
  ],
  "filters": {
    "type": "contextAttribute",
    "attribute": "country",
    "values": [
      "JP"
    ],
    "contextKind": "user"
  },
  "unitAggregationType": "average",
  "analysisType": "mean",
  "percentileValue": 95,
  "experiments": [
    {
      "key": "experiment-key-123abc",
      "name": "Example experiment",
      "environmentId": "1234a56b7c89d012345e678f",
      "environmentKey": "production",
      "_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",
    "_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",
    "_links": {
      "self": {
        "href": "/api/v2/projects/my-project/flags/my-flag/environments/production/measured-rollouts/885ccadf-181b-4a9a-8414-7ad6f7ba2db0",
        "type": "application/json"
      }
    }
  },
  "isActive": true,
  "_attachedFeatures": [
    {
      "name": "Example flag",
      "key": "flag-key-123abc"
    }
  ]
}