Metrics API - GET metrics

Lists all available metrics.

You can limit the output by using the pagination:

  1. Specify the number of results per page in the pageSize query parameter.
  2. Then use the cursor from the nextPageKey field of the previous response in the nextPageKey query parameter to obtain subsequent pages.

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.

GET
  • Managed https://{your-domain}/e/{your-environment-id}/api/v2/metrics
  • SaaS https://{your-environment-id}.live.dynatrace.com/api/v2/metrics

Authentication

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

Parameters

Parameter Type Description In Required
nextPageKey string

The cursor for the next page of results. You can find it in the nextPageKey field of the previous response.

The first page is always returned if you don't specify the nextPageKey query parameter.

When the nextPageKey is set to obtain subsequent pages, you must omit all other query parameters.

query optional
pageSize integer

The desired amount of primary entities in a single response payload.

The maximal allowed page size is 5000.

If not set, 100 is used.

If a value higher than 5000 is used, only 5000 results per page are returned.

query optional
metricSelector string

Selects metrics for the query by their keys.

You can specify multiple metric keys separated by commas (for example, metrickey1,metrickey2). To select multiple metrics belonging to the same parent, list the last part of the required metric keys in parentheses, separated by commas, while keeping the common part untouched. For example, to list the builtin:host.cpu.idle and builtin:host.cpu.user metric, write: builtin:host.cpu.(idle,user).

You can select a full set of related metrics by using a trailing asterisk (*) wildcard. For example, builtin:host.* selects all host-based metrics and builtin:* selects all Dynatrace-provided metrics.

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.

To find metrics based on a search term, rather than metricID, use the text query parameter instead of this one.

query optional
text string

Metric registry search term. Only show metrics that contain the term in their ID, display name, or description. Use the metricSelector parameter instead of this one to select a complete metric hierarchy instead of doing a text-based search.

query optional
fields string

Defines the list of metric properties included in the response.

metricId is always included in the result. The following additional properties are available:

  • displayName: The name of the metric in the user interface. Enabled by default.
  • description: A short description of the metric. Enabled by default.
  • unit: The unit of the metric. Enabled by default.
  • dduBillable: An indicator whether the usage of metric consumes Davis data units.
  • aggregationTypes: The list of allowed aggregations for the metric. Note that it may be different after a transformation is applied.
  • defaultAggregation: The default aggregation of the metric. It is used when no aggregation is specified or the :auto transformation is set.
  • dimensionDefinitions: The fine metric division (for example, process group and process ID for some process-related metric).
  • transformations: A list of transformations that can be applied to the metric.
  • entityType: A list of entity types supported by the metric.

To add properties, list them with leading plus +. To exclude default properties, list them with leading minus -.

To specify several properties, join them with a comma (for example fields=+aggregationTypes,-description).

If you specify just one property, the response contains the metric key and the specified property.To return metric keys only, specify metricId here.

query optional
writtenSince

Filters the resulted set of metrics to those that have data points within the specified timeframe

.You can use one of the following formats:

  • Timestamp in UTC milliseconds.
  • Human-readable format of 2019-12-21T05:57:01.123+01:00. If no time zone is specified, UTC is used. You can use a space character instead of the T. Seconds and fractions of a second are optional.
  • Relative timeframe, back from now. The format is now-NU/A, where N is the amount of time, U is the unit of time, and A is an alignment. The alignment rounds all the smaller values to the nearest zero in the past. For example, now-1y/w is one year back, aligned by a week. You can also specify relative timeframe without an alignment: now-NU. Supported time units for the relative timeframe are:
  • m: minutes
  • h: hours
  • d: days
  • w: weeks
  • M: months
  • y: years
query optional

The LastWrittenDto object

Element Type Description Required
validatedTimestamp integer optional
timeFormatExpression string optional

Response format

The MetricDescriptorCollection object

A list of metrics along with their descriptors.

Element Type Description
totalCount integer

The estimated number of metrics in the result.

metrics MetricDescriptor[]

A list of metric along with their descriptors

nextPageKey string

The cursor for the next page of results. Has the value of null on the last page.

Use it in the nextPageKey query parameter to obtain subsequent pages of the result.

The MetricDescriptor object

The descriptor of a metric.

Element Type Description
aggregationTypes string[]

The list of allowed aggregations for this metric.

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.

defaultAggregation MetricDefaultAggregation
dimensionDefinitions MetricDimensionDefinition[]

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

lastWritten integer

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

dduBillable boolean

If true the usage of metric consumes Davis data units.

displayName string

The name of the metric in the user interface.

description string

A short description of the metric.

unit string

The unit of the metric.

The unit element can hold these values.
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}.

created integer

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

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.

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.

Possible values

Possible values for the transformations element in the MetricDescriptor object:

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

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 type element in the MetricDimensionDefinition object:

  • ENTITY
  • NUMBER
  • OTHER
  • STRING
  • VOID

Possible values for the type element in the MetricDefaultAggregation object:

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

Possible values for the aggregationTypes element in the MetricDescriptor object:

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

Example

In this example, the request queries all built-in metrics (metricSelector is set to builtin:*) available in the mySampleEnv environment. The following fields are included in the response:

  • metricId
  • unit
  • aggregationTypes

To achieve that, the fields query parameter is set to unit,aggregationTypes.

The API token is passed in the Authorization header.

The response is in application/json format and is truncated to four entries.

Curl

curl -L -X GET 'https://mySampleEnv.live.dynatrace.com/api/v2/metrics?fields=unit,aggregationTypes&metricSelector=builtin:*' \
-H 'Authorization: Api-Token abcdefjhij1234567890' \
-H 'Accept: application/json'

Request URL

https://mySampleEnv.live.dynatrace.com/api/v2/metrics?fields=unit,aggregationTypes&metricSelector=builtin:*

Response body

{
  "totalCount": 1808,
  "nextPageKey": "___a7acX3q0AAAAGAQAJYnVpbHRpbjoqAQA",
  "metrics": [
    {
      "metricId": "builtin:host.cpu.idle",
      "unit": "Percent",
      "aggregationTypes": [
        "auto",
        "avg",
        "max",
        "min"
      ]
    },
    {
      "metricId": "builtin:host.cpu.load",
      "unit": "Ratio",
      "aggregationTypes": [
        "auto",
        "avg",
        "max",
        "min"
      ]
    },
    {
      "metricId": "builtin:service.errors.server.count",
      "unit": "Count",
      "aggregationTypes": [
        "auto",
        "value"
      ]
    },
    {
      "metricId": "builtin:service.keyRequest.count.client",
      "unit": "Count",
      "aggregationTypes": [
        "auto",
        "value"
      ]
    }
  ]
}

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

metricId,unit,aggregationTypes
builtin:host.cpu.idle,Percent,"[auto, avg, max, min]"
builtin:host.cpu.load,Ratio,"[auto, avg, max, min]"
builtin:service.errors.server.count,Count,"[auto, value]"
builtin:service.keyRequest.count.client,Count,"[auto, value]"

Response code

200