Metrics API - GET metric data points

Gets data points of the specified metrics.

You can receive either one aggregated data point per series or a list of data points per series. See the description of the resolution parameter of the request for more information.

The following limits apply:

  • The number of aggregated data points in the response is limited to 1,000
  • The number of series in the response is limited to 1,000
    • The number of data points per series is limited to 10,080
    • The overall number of data points is limited to 100,000

The request produces an application/json payload.

This request is an early adopter release and may be changed in non compatible way.

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

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. nextPageKey is set to null on the last page.

query optional
pageSize integer

The desired amount of primary entities for which data is delivered in a single response payload.

The maximal allowed page size is 1000.

If not set, 100 is used.

query optional
metricSelector string

Selects metrics for the query by their keys. You can select up to 10 metrics for one query.

You can specify multiple metric keys separated by commas. For example: metrickey1,metrickey2.

To select multiple metrics belonging to the same parent, you can use this shorthand: 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, you could write: builtin:host.cpu.(idle,user).

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 selector string is limited to 1,000 characters.

query optional
resolution string

The desired resolution of data points.

You can use one of the following options:

  • One aggregated data point of each series. Set Inf to use this option.
  • The desired amount of data points. This is the default option. This is a reference number of points, which is not necessarily equal to the number of the returned data points.
  • The desired timespan between data points. This is a reference timespan, which is not necessarily equal to the returned timespan. To use this option, specify the unit of the timespan.

Valid units for the timespan are:

  • m: minutes
  • h: hours
  • d: days
  • w: weeks
  • M: months
  • y: years

If not set, the default is 120 data points.

query optional
from string

The start of the requested 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. For example, now-1y/w is one year back, aligned by a week. The alignment rounds to the past. Supported time units for the relative timeframe are:
  • m: minutes
  • h: hours
  • d: days
  • w: weeks
  • M: months
  • y: years

If not set, the relative timeframe of two weeks is used (now-2w).

query optional
to string

The end of the requested 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. For example, now-1y/w is one year back, aligned by a week. The alignment rounds to the past. Supported time units for the relative timeframe are:
  • m: minutes
  • h: hours
  • d: days
  • w: weeks
  • M: months
  • y: years

If not set, the current timestamp is used.

query optional
entitySelector string

Specifies the entity scope of the query.

You can set one or several of the following criteria:

  • Mandatory entity type: type(HOST).
  • Tag: tag(value)
  • Management zone ID: mzId(value)
  • Entity id: entityId(id1,..,idn). You can specify several entity ids, separated by a comma (,).
  • Entity name: entityName(value1,value2). You can specify several entity names, separated by a comma (,). To set several criteria, separate them with a comma (,). Only results, matching all criteria, are included into response. The scope is limited to 10,000 entities. If your scope exceeds 10,000 entities, split it into several queries.

You can't use dimensions in the scope. You can, however, use the filter transformation operator on the metric selector. See the Metrics API - selector transformations help page for additional information on available transformation operators.

To set a universal scope, matching all entities, omit this parameter.

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

query optional

Response format

The MetricQueryResultDto object

A list of metric data for one or more metrics.

Element Type Description
result MetricDataDto[]

List of per-metric results.

totalCount integer

Estimated maximum amount of primary entities over all pages.

nextPageKey string

Key to the next page for use with nextPageKey, or null for the last page.

The MetricDataDto object

Data for a single metric returned from a query or to be ingested.

Element Type Description
data MetricDataRecordDto[]

Data series for each result tuple that was queried or should be ingested.

metricId string

The fully qualified key of the metric from which the data was read or should be written to, followed by an optional transform operator chain.

The MetricDataRecordDto object

Result data for a single combination of dimension values.

Element Type Description
dimensions string[]

The ordered list of dimensions to which the data point list belongs.

Each metric can have a certain number of dimensions. Dimensions exceeding this number are aggregated into one, which is shown as null here.

values number[]

The data point values associated with each ending timestamp.

Each entry in timestamps has an entry in this array with the same index that indicates the value of the metric at that time. The length is the same as the length of the timestamps array.

timestamps integer[]

The associated timestamps for each data point value.

Each entry in values has an entry in this array with the same index that indicates the ending time stamp of that data point. The length is the same as the length of the values array.

Timeframe note

Dynatrace stores data in time slots. The MetricValue object shows the ending timestamp of the slot. If the time, set in the from or to parameters of your query, falls within the data time slot, this time slot is included in the response.

If the timestamp of the last data slot lays outside of the specified timeframe, the last data point of the response has a later timestamp than the specified in to query parameter.

Dynatrace does not predict future data. The timestamp of the last data point may lay in the future, due to data slots principle, described above. In this case, this data slot has incomplete data.

Timeslot scheme

Examples

In these examples, the requests query the data points of the builtin:host.cpu.usage and builtin:host.cpu.idle metrics. The scope is limited to the management zone with the ID of 9130632296508575249. The timeframe is not specified, so the default timeframe of 2 weeks back from now is used.

The API token is passed in the Authorization header.

The difference between the queries is the representation of data—the first shows the list of data points, while the second shows just one aggregated data point for each series.

The result is truncated to two series per metric and three data points per series for the list of data points.

Curl

curl -X GET \
  'https://mySampleEnv.live.dynatrace.com/api/v2/metrics/series/builtin:host.cpu.%28usage,idle%29?scope=mzid%289130632296508575249%29&resolution=100' \
  -H 'Authorization: Api-Token abcdefjhij1234567890'

Request URL

https://mySampleEnv.live.dynatrace.com/api/v2/metrics/series/builtin:host.cpu.%28usage,idle%29?scope=mzid%289130632296508575249%29&resolution=100

Response body

{
  "metrics": {
    "builtin:host.cpu.usage": {
      "series": [
        {
          "dimensions": [
            "HOST-661B5DDFE19DB5AE"
          ],
          "values": [
            {
              "timestamp": 1559563200000,
              "value": 0.7537290219907408
            },
            {
              "timestamp": 1559574000000,
              "value": 0.6646773726851852
            },
            {
              "timestamp": 1559584800000,
              "value": 0.6338252314814815
            }
          ]
        },
        {
          "dimensions": [
            "HOST-7CF622A2AB0AFFD3"
          ],
          "values": [
            {
              "timestamp": 1559563200000,
              "value": 2.614283130787037
            },
            {
              "timestamp": 1559574000000,
              "value": 2.5198640046296297
            },
            {
              "timestamp": 1559584800000,
              "value": 2.3291558159722223
            }
          ]
        }
      ]
    },
    "builtin:host.cpu.idle": {
      "series": [
        {
          "dimensions": [
            "HOST-661B5DDFE19DB5AE"
          ],
          "values": [
            {
              "timestamp": 1559563200000,
              "value": 99.24627097800926
            },
            {
              "timestamp": 1559574000000,
              "value": 99.33532262731481
            },
            {
              "timestamp": 1559584800000,
              "value": 99.36617476851852
            }
          ]
        },
        {
          "dimensions": [
            "HOST-7CF622A2AB0AFFD3"
          ],
          "values": [
            {
              "timestamp": 1559563200000,
              "value": 97.38571686921296
            },
            {
              "timestamp": 1559574000000,
              "value": 97.48013599537038
            },
            {
              "timestamp": 1559584800000,
              "value": 97.67084418402777
            }
          ]
        }
      ]
    }
  }
}

Response code

200