Migrate from Timeseries v1 API to Metrics v2 API

  • Reference

The Timeseries API v1 has been deprecated. Its replacement is Metrics API v2 with the Maintenance windows (builtin:alerting.maintenance-window) schema. We recommend that you migrate to the new API at your earliest convenience.

The migration affects endpoint URLs, query parameters, and response/request body parameters, as well as the scope of the token for request authentication.

Base URL

new Metrics v2
old Timeseries v1
/api/v2/metrics
/api/v1/timeseries

Authentication token scope

new Metrics v2
old Timeseries v1
Read metrics (metrics.read)
Write metrics (metrics.write)
Data Export (DataExport)

Parameters

To learn about new query/body parameters, see the documentation of individual requests in Metrics API v2.

Examples

Here are some examples of differences in API usage.

Get list of metrics

This example lists all metrics.

Request URL

https://mySampleEnv.live.dynatrace.com/api/v2/metrics

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"
]
}
]
}

Get metric description

In this example, the request queries the parameters of a single metric.

Request URL

https://mySampleEnv.live.dynatrace.com/api/v2/metrics/builtin:host.disk.avail

Request body

{
"metricId": "builtin:host.disk.avail",
"displayName": "Disk available",
"description": "",
"unit": "Byte",
"entityType": [
"HOST"
],
"aggregationTypes": [
"auto",
"avg",
"max",
"min"
],
"transformations": [
"filter",
"fold",
"merge",
"names",
"parents"
],
"defaultAggregation": {
"type": "avg"
},
"dimensionDefinitions": [
{
"key": "dt.entity.host",
"name": "Host",
"index": 0,
"type": "ENTITY"
},
{
"key": "dt.entity.disk",
"name": "Disk",
"index": 1,
"type": "ENTITY"
}
]
}

Get metric data

In these examples, the requests query the data points of a metric for the last hour.

Request URL

https://mySampleEnv.live.dynatrace.com/api/v2/metrics/query?metricSelector=builtin:host.cpu.usage&from=now-1h

Response body

{
"totalCount": 1,
"nextPageKey": null,
"result": [
{
"metricId": "builtin:host.cpu.usage",
"dataPointCountRatio": 1.8E-5,
"dimensionCountRatio": 3.0E-5,
"data": [
{
"dimensions": [
"HOST-0990886B7D39FE29"
],
"dimensionMap": {
"dt.entity.host": "HOST-0990886B7D39FE29"
},
"timestamps": [
1589456100000,
1589456160000,
1589456220000
],
"values": [
19.0,
19.0,
21.0
]
},
{
"dimensions": [
"HOST-0956C3557E9109C1"
],
"dimensionMap": {
"dt.entity.host": "HOST-0956C3557E9109C1"
},
"timestamps": [
1589456100000,
1589456160000,
1589456220000
],
"values": [
19.0,
21.0,
22.0
]
}
]
}
]
}