Custom metric metadata

To add more context to data points and their dimensions, your custom metric can carry additional useful information, such as the unit of measurement, display name, and value ranges.

You can provide such information via custom metric metadata. Metadata and data points are stored independently from data points and tied together by the metric key. You can push data points and set metadata in any order.

You cannot provide metadata for built-in or calculated metrics; metadata is supported only for custom ingested metrics.

Available parameters

The following parameters are available for metric metadata.

Set metric metadata

Use the POST an object call of the Settings API to provide metadata for your metric. Use the following parameters in the payload:

Field
Value
scope
metric-{your-metric-key}
schemaId
builtin:metric.metadata
value
The desired set of metadata. See the available fields above.
[
  {
    "scope": "metric-business.shop.revenue",
    "schemaId": "builtin:metric.metadata",
    "value": {
      "displayName": "Total revenue",
      "description": "Total store revenue by region, city, and store",
      "unit": "Unspecified",
      "tags": ["KPI", "Business"],
      "metricProperties": {
        "maxValue": 1000000,
        "minValue": 0,
        "rootCauseRelevant": false,
        "impactRelevant": true,
        "valueType": "score",
        "latency": 1
      },
      "dimensions": [
        {
          "key": "city",
          "displayName": "City name"
        },
        {
          "key": "country",
          "displayName": "Country name"
        },
        {
          "key": "region",
          "displayName": "Sales region"
        },
        {
          "key": "store",
          "displayName": "Store #"
        }
      ]
    }
  }
]

Alternatively, you can:

View metric metadata

You can retrieve the metadata of a metric via the GET metric descriptor call of the Metrics v2 API or via the Metrics browser.

Related topics