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

Authentication

To execute this request, you need the Access problem and event feed, metrics, and topology (DataExport) permission assigned to your API token. To learn how to obtain and use it, see 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 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, 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 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 scope of the query. Only data points delivered by matched entities are included in response.

You can set one or several of the following criteria:

  • Entity type (required): type("value").
  • Tag: tag("value"). Tags in [context]key:value, key:value, and value formats are detected and parsed automatically. If a value-only tag has a colon (:) in it, you must escape the colon with a backslash(\). Otherwise, the tag will be parsed as a key:value tag. All tag values are case-sensitive.
  • Management zone ID: mzId("ID")
  • Management zone name: mzName("value"). Management zone names are case-sensitive.
  • Health state (HEALTHY,UNHEALTHY): healthState("HEALTHY")
  • Dynatrace entity ID: entityId("id"). You can specify several IDs, separated by a comma (entityId("id-1","id-2")).
  • Dynatrace entity name: entityName("value"). You can specify several entity names, separated by a comma (entityName("name-1","name-2")). Entity names are case-sensitive.

To set several criteria, separate them with a comma (,). For example, type("HOST"),healthState("HEALTHY"). Only results matching all criteria are included in response.

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

Use the GET /metrics/{metricId} call to fetch the list of possible entity types for your metric.

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

query optional

Response format

The MetricData object

A list of metrics and their data points.

Element Type Description
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.

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.

result MetricSeriesCollection[]

A list of metrics and their data points.

The MetricSeriesCollection 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 MetricSeries[]

Data points of the metric.

The MetricSeries object

Data points per dimension of a metric.

The data is represented by two arrays of the same length: timestamps and values. Entries of the same index from both arrays form a timestamped data point.

Element Type Description
timestamps integer[]

A list of timestamps of data points.

The value of data point for each time from this array is located in values array at the same index.

values number[]

A list of values of data points.

The timestamp of data point for each value from this array is located in timestamps array at the same index.

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.

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 timeframe is set to last 5 minutes. To achieve that, the from query parameter is set to now-5m.

Only data from these two hosts (HOST-0990886B7D39FE29 and HOST-0956C3557E9109C1) is included to the response. To achieve that, the entitySelector query parameter is set to type("HOST"),entityId("HOST-0990886B7D39FE29").

Because host is a dimension of the queried metrics, you can achieve the same filtering by applying the :filter transformation to the metrics themselves by setting the metricSelector query parameter to builtin:host.cpu.(usage,idle):filter(or(eq(Host,HOST-0990886B7D39FE29),eq(Host,HOST-0956C3557E9109C1))) and omitting entitySelector as redundant.

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 (resolution is set to Inf).

The API token is passed in the Authorization header.

The response is in application/json format.

Curl

With untransformed metrics and entitySelector filter:

curl -L -X GET 'https://mySampleEnv.live.dynatrace.com/api/v2/metrics/query?metricSelector=builtin:host.cpu.(usage,idle)&entitySelector=type(%22HOST%22),entityId(%22HOST-0990886B7D39FE29%22,%22HOST-0956C3557E9109C1%22)&from=now-5m' \
-H 'Authorization: Api-Token abcdefjhij1234567890' \
-H 'Accept: application/json'

With transformation applied directly to the metrics:

curl -L -X GET 'https://mySampleEnv.live.dynatrace.com/api/v2/metrics/query?metricSelector=builtin:host.cpu.(usage,idle):filter(or(eq(Host,HOST-0990886B7D39FE29),eq(Host,HOST-0956C3557E9109C1)))&from=now-5m' \
-H 'Authorization: Api-Token abcdefjhij1234567890' \
-H 'Accept: application/json'

Request URL

With untransformed metrics and entitySelector filter:

https://mySampleEnv.live.dynatrace.com/api/v2/metrics/query?metricSelector=builtin:host.cpu.(usage,idle)&entitySelector=type(%22HOST%22),entityId(%22HOST-0990886B7D39FE29%22,%22HOST-0956C3557E9109C1%22)&from=now-5m

With transformation applied directly to the metrics:

https://mySampleEnv.live.dynatrace.com/api/v2/metrics/query?metricSelector=builtin:host.cpu.(usage,idle):filter(or(eq(Host,HOST-0990886B7D39FE29),eq(Host,HOST-0956C3557E9109C1)))&from=now-5m

Response body

The result is truncated to three data points per dimension.

{
  "totalCount": 2,
  "nextPageKey": null,
  "result": [
    {
      "metricId": "builtin:host.cpu.idle",
      "data": [
        {
          "dimensions": [
            "HOST-0990886B7D39FE29"
          ],
          "timestamps": [
            1589456100000,
            1589456160000,
            1589456220000
          ],
          "values": [
            81.0,
            81.0,
            79.0
          ]
        },
        {
          "dimensions": [
            "HOST-0956C3557E9109C1"
          ],
          "timestamps": [
            1589456100000,
            1589456160000,
            1589456220000
          ],
          "values": [
            81.0,
            79.0,
            78.0
          ]
        }
      ]
    },
    {
      "metricId": "builtin:host.cpu.usage",
      "data": [
        {
          "dimensions": [
            "HOST-0990886B7D39FE29"
          ],
          "timestamps": [
            1589456100000,
            1589456160000,
            1589456220000
          ],
          "values": [
            19.0,
            19.0,
            21.0
          ]
        },
        {
          "dimensions": [
            "HOST-0956C3557E9109C1"
          ],
          "timestamps": [
            1589456100000,
            1589456160000,
            1589456220000
          ],
          "values": [
            19.0,
            21.0,
            22.0
          ]
        }
      ]
    }
  ]
}

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

metricId,Host,time,value
builtin:host.cpu.usage,HOST-0956C3557E9109C1,2020-05-14 11:35:00,19.0
builtin:host.cpu.usage,HOST-0956C3557E9109C1,2020-05-14 11:36:00,19.0
builtin:host.cpu.usage,HOST-0956C3557E9109C1,2020-05-14 11:37:00,21.0
builtin:host.cpu.usage,HOST-0990886B7D39FE29,2020-05-14 11:35:00,19.0
builtin:host.cpu.usage,HOST-0990886B7D39FE29,2020-05-14 11:36:00,21.0
builtin:host.cpu.usage,HOST-0990886B7D39FE29,2020-05-14 11:37:00,22.0

Response code

200