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.

GET
  • Managed https://{your-domain}/e/{your-environment-id}/api/v2/metrics/query
  • SaaS https://{your-environment-id}.live.dynatrace.com/api/v2/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.

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 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 selector of the query.

You can set one or several of the following criteria:

  • Entity type (required): type(HOST).
  • Tag: tag(value)
  • Management zone ID: mzId(ID)
  • Dynatrace entity ID: entityId(id). You can specify several IDs, separated by a comma (id-1,id-2).
  • Entity name: entityName(value). You can specify several entity names, separated by a comma (id-1,id-2).

To set several criteria, separate them with a comma (,). Only results matching all criteria are included into response.

Use the GET /metrics/{metricId} call to find out which entity types the metric you're interested in supports.

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

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

query optional

Response format

The MetricData object

A list of metrics and their data points.

Element Type Description
totalCount integer

The total number of primary entities in the result.

Has the 0 value if none of the requested metrics is suitable for pagination.

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.

result MetricDataPoints[]

A list of metrics and their data points.

The MetricDataPoints object

Data points of a metric.

Element Type Description
metricId string

The key of the metric.

If any transformation is applied, it is included here.

data MetricDataPoints[]

Data points of the metric.

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