Metrics API - GET metric descriptor

Gets the parameters of the specified metric.

The request produces one of the following types of payload, depending on the value of the the Accept request header:

  • application/json
  • text/csv; header=present—a CSV table with header row
  • text/csv; header=absent—a CSV table without header row

If no Accept header is provided with the request, an application/json payload is returned.

  • Managed https://{your-domain}/e/{your-environment-id}/api/v2/metrics/{metricId}
  • SaaS https://{your-environment-id}{metricId}


To execute this request, you need the Read metrics ( permission assigned to your API token. To learn how to obtain and use it, see Tokens and authentication.


Parameter Type Description In Required
metricId string

The key of the required metric.

You can set additional transformation operators, separated by a colon (:). See the Metrics API - selector transformations help page for additional information on available result transformations.

The length of the string is limited to 1,000 characters.

path required

Response format

The MetricDescriptor object

The descriptor of a metric.

Element Type Description
entityType string[]

List of admissible primary entity types for this metric. Can be used for the type predicate in the entitySelector.

metricId string

The fully qualified key of the metric.

If a transformation has been used it is reflected in the metric key.

aggregationTypes string[]

The list of allowed aggregations for this metric.

dduBillable boolean

If true the usage of metric consumes Davis data units.

lastWritten integer

The timestamp when the metric was last written. if never.

dimensionDefinitions MetricDimensionDefinition[]

The fine metric division (for example, process group and process ID for some process-related metric).

defaultAggregation MetricDefaultAggregation
description string

A short description of the metric.

transformations string[]

Transform operators that could be appended to the current transformation list. Must be enabled with the "fields" parameter on /metrics and is always present on /metrics/{metricId}.

unit string

The unit of the metric.

The unit element can hold these values.
created integer

The timestamp when the metric was created. for builtin metrics.

displayName string

The name of the metric in the user interface.

The MetricDefaultAggregation object

The default aggregation of a metric.

Element Type Description
parameter number

The percentile to be delivered. Valid values are between 0 and 100.

Applicable only to the percentile aggregation type.

type string

The type of default aggregation.

The type element can hold these values.

The MetricDimensionDefinition object

The dimension of a metric.

Element Type Description
index integer

The unique 0-based index of the dimension.

Appending transformations such as :names or :parents may change the indexes of dimensions. null is used for the dimensions of a metric with flexible dimensions, which can be referenced with their dimension key, but do not have an intrinsic order that could be used for the index.

name string

The name of the dimension.

key string

The key of the dimension.

It must be unique within the metric.

type string

The type of the dimension.

The type element can hold these values.
displayName string

The display name of the dimension.

Possible values

Possible values for the unit element in the MetricDescriptor object:

  • Bit
  • BitPerHour
  • BitPerMinute
  • BitPerSecond
  • Byte
  • BytePerHour
  • BytePerMinute
  • BytePerSecond
  • Cores
  • Count
  • Day
  • DecibelMilliWatt
  • GibiByte
  • Giga
  • GigaByte
  • Hour
  • KibiByte
  • KibiBytePerHour
  • KibiBytePerMinute
  • KibiBytePerSecond
  • Kilo
  • KiloByte
  • KiloBytePerHour
  • KiloBytePerMinute
  • KiloBytePerSecond
  • MebiByte
  • MebiBytePerHour
  • MebiBytePerMinute
  • MebiBytePerSecond
  • Mega
  • MegaByte
  • MegaBytePerHour
  • MegaBytePerMinute
  • MegaBytePerSecond
  • MicroSecond
  • MilliCores
  • MilliSecond
  • MilliSecondPerMinute
  • Minute
  • Month
  • NanoSecond
  • NanoSecondPerMinute
  • NotApplicable
  • PerHour
  • PerMinute
  • PerSecond
  • Percent
  • Pixel
  • Promille
  • Ratio
  • Second
  • State
  • Unspecified
  • Week
  • Year

Possible values for the transformations element in the MetricDescriptor object:

  • filter
  • fold
  • last
  • limit
  • merge
  • names
  • parents
  • rate
  • sort
  • splitBy
  • timeshift

Possible values for the type element in the MetricDefaultAggregation object:

  • auto
  • avg
  • count
  • max
  • median
  • min
  • percentile
  • sum
  • value

Possible values for the type element in the MetricDimensionDefinition object:

  • VOID

Possible values for the aggregationTypes element in the MetricDescriptor object:

  • auto
  • avg
  • count
  • max
  • median
  • min
  • percentile
  • sum
  • value


In this example, the request queries the parameters of three metrics: builtin:host.cpu.idle, builtin:host.cpu.usage, and builtin:host.disk.avail.

The builtin:host.cpu.idle and builtin:host.cpu.usage metrics have the same parent and their selector is combined into builtin:host.cpu.(idle,usage).

The response is in application/json format.


curl -L -X GET '' \
-H 'Authorization: Api-Token abcdefjhij1234567890' \
-H 'Accept: application/json'

Request URL

Response body

  "metricId": "builtin:host.disk.avail",
  "displayName": "Disk available",
  "description": "",
  "unit": "Byte",
  "entityType": [
  "aggregationTypes": [
  "transformations": [
  "defaultAggregation": {
    "type": "avg"
  "dimensionDefinitions": [
      "key": "",
      "name": "Host",
      "index": 0,
      "type": "ENTITY"
      "key": "dt.entity.disk",
      "name": "Disk",
      "index": 1,
      "type": "ENTITY"

The CSV table with header row looks like this. To obtain it, change the Accept header to text/csv; header=present.

builtin:host.cpu.usage,CPU usage %,Percentage of CPU time currently utilized.,Percent,[HOST],"[auto, avg, max, min]","[filter, fold, merge, names, parents]",avg,[Host:ENTITY]

Response code