• Home
  • Dynatrace API
  • Environment
  • Timeseries v1
  • Metric definitions
  • GET definition of a metric

Timeseries API v1 - GET definition of a metric

We have a new version of this API—Metrics API v2. Check it out!

Gets the definition of the specified metric.

The request produces an application/json payload.

GETManagedDynatrace for Governmenthttps://{your-domain}/e/{your-environment-id}/api/v1/timeseries/{timeseriesIdentifier}
SaaShttps://{your-environment-id}.live.dynatrace.com/api/v1/timeseries/{timeseriesIdentifier}
Environment ActiveGatehttps://{your-activegate-domain}/e/{your-environment-id}/api/v1/timeseries/{timeseriesIdentifier}

Authentication

To execute this request, you need an access token with DataExport scope.

To learn how to obtain and use it, see Tokens and authentication.

Parameters

To get a definition of the metric but not its data points, set the includeData parameter to false.

ParameterTypeDescriptionInRequired
timeseriesIdstringCase-sensitive ID of the metric from which you want to read parameters.

You can execute a GET metric definitions request to obtain the list of available metrics.
pathrequired
includeDatabooleanFlag to include data points to the response. Set to false to obtain just the definition of the metric.queryoptional

Response

The result is a JSON object that contains metric parameters. The TimeseriesDataPointQueryResult object is omitted in this case.

Response codes

CodeTypeDescription
200TimeseriesQueryResult

Success

Response body objects

The TimeseriesQueryResult object

The configuration of a metric with all its parameters and, optionally, data points.

ElementTypeDescription
timeseriesIdstring

The ID of the metric.

displayNamestring

The name of the metric in the user interface.

dimensionsstring[]

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

aggregationTypesstring[]

The list of allowed aggregations for this metric.

The element can hold these values
  • AVG
  • COUNT
  • MAX
  • MEDIAN
  • MIN
  • PERCENTILE
  • SUM
unitstring

The unit of the metric.

The element can hold these values
  • Billion (Gcount)
  • Bit (bit)
  • BitPerHour (bit/h)
  • BitPerMinute (bit/min)
  • BitPerSecond (bit/s)
  • Byte (B)
  • BytePerHour (B/h)
  • BytePerMinute (B/min)
  • BytePerSecond (B/s)
  • Cores
  • Count (count)
  • Day (ds)
  • DecibelMilliWatt (dBm)
  • G
  • GibiByte (GiB)
  • GibiBytePerHour (GiB/h)
  • GibiBytePerMinute (GiB/min)
  • GibiBytePerSecond (GiB/s)
  • GigaByte (GB)
  • GigaBytePerHour (GB/h)
  • GigaBytePerMinute (GB/min)
  • GigaBytePerSecond (GB/s)
  • Hour (hs)
  • KibiByte (KiB)
  • KibiBytePerHour (KiB/h)
  • KibiBytePerMinute (KiB/min)
  • KibiBytePerSecond (KiB/s)
  • KiloByte (kB)
  • KiloBytePerHour (kB/h)
  • KiloBytePerMinute (kB/min)
  • KiloBytePerSecond (kB/s)
  • M
  • MSU
  • MebiByte (MiB)
  • MebiBytePerHour (MiB/h)
  • MebiBytePerMinute (MiB/min)
  • MebiBytePerSecond (MiB/s)
  • MegaByte (MB)
  • MegaBytePerHour (MB/h)
  • MegaBytePerMinute (MB/min)
  • MegaBytePerSecond (MB/s)
  • MicroSecond (µs)
  • MilliSecond (ms)
  • MilliSecondPerMinute (ms/min)
  • Million (Mcount)
  • Minute (mins)
  • Month (mos)
  • N/A
  • NanoSecond (ns)
  • NanoSecondPerMinute (ns/min)
  • PerHour (count/h)
  • PerMinute (count/min)
  • PerSecond (count/s)
  • Percent (%)
  • Pixel (px)
  • Promille (‰)
  • Ratio
  • Second (s)
  • State
  • Trillion (Tcount)
  • Unspecified
  • Week (ws)
  • Year (ys)
  • k
  • km/h
  • m/h
  • m/s
  • mCores
filterstring

The feature, where the metric originates.

The element can hold these values
  • ALL
  • BUILTIN
  • CUSTOM
  • PLUGIN
  • REMOTE_PLUGIN
detailedSourcestring

The feature, where the metric originates.

pluginIdstring

The ID of the plugin, where the metric originates.

typesstring[]

Technology type definition. Used to group metrics under a logical technology name.

dataResultTimeseriesDataPointQueryResult

List of metric's datapoints, as well as their parameters.

warningsstring[]

The warnings that occurred while creating the metric.

The TimeseriesDataPointQueryResult object

List of metric's datapoints, as well as their parameters.

ElementTypeDescription
dataPointsobject

Data points of a metric.

A JSON object that maps the ID of the entity that delivered the data points and an array, which consists of arrays of the data point float values.

May contain more than one entity ID per record (for example, a host and its network interface). In such cases, entity IDs are separated by commas.

A datapoint contains a value and a timestamp, at which the value was recorded.

Dynatrace stores data in time slots. The dataPoints object shows the starting timestamp of the slot. If the startTimestamp or endTimestamp of your query lies inside of the data time slot, this time slot is included into response. Due to the fact that the timestamp of the first data point lies outside of the specified timeframe, you will see earlier timestamp than the specified startTimestamp in the first data point of the response.

There are three versions of data points:

  • Numeric datapoint: Contains a numeric value.
  • Enum datapoint: Contains an enum value, currently only for availability timeseries.
  • Prediction datapoint: Similar to the numeric datapoint, but it contains a confidence interval, within which the future values are expected to be.
timeseriesIdstring

The ID of the metric.

unitstring

The unit of data points.

The element can hold these values
  • Billion (Gcount)
  • Bit (bit)
  • BitPerHour (bit/h)
  • BitPerMinute (bit/min)
  • BitPerSecond (bit/s)
  • Byte (B)
  • BytePerHour (B/h)
  • BytePerMinute (B/min)
  • BytePerSecond (B/s)
  • Cores
  • Count (count)
  • Day (ds)
  • DecibelMilliWatt (dBm)
  • G
  • GibiByte (GiB)
  • GibiBytePerHour (GiB/h)
  • GibiBytePerMinute (GiB/min)
  • GibiBytePerSecond (GiB/s)
  • GigaByte (GB)
  • GigaBytePerHour (GB/h)
  • GigaBytePerMinute (GB/min)
  • GigaBytePerSecond (GB/s)
  • Hour (hs)
  • KibiByte (KiB)
  • KibiBytePerHour (KiB/h)
  • KibiBytePerMinute (KiB/min)
  • KibiBytePerSecond (KiB/s)
  • KiloByte (kB)
  • KiloBytePerHour (kB/h)
  • KiloBytePerMinute (kB/min)
  • KiloBytePerSecond (kB/s)
  • M
  • MSU
  • MebiByte (MiB)
  • MebiBytePerHour (MiB/h)
  • MebiBytePerMinute (MiB/min)
  • MebiBytePerSecond (MiB/s)
  • MegaByte (MB)
  • MegaBytePerHour (MB/h)
  • MegaBytePerMinute (MB/min)
  • MegaBytePerSecond (MB/s)
  • MicroSecond (µs)
  • MilliSecond (ms)
  • MilliSecondPerMinute (ms/min)
  • Million (Mcount)
  • Minute (mins)
  • Month (mos)
  • N/A
  • NanoSecond (ns)
  • NanoSecondPerMinute (ns/min)
  • PerHour (count/h)
  • PerMinute (count/min)
  • PerSecond (count/s)
  • Percent (%)
  • Pixel (px)
  • Promille (‰)
  • Ratio
  • Second (s)
  • State
  • Trillion (Tcount)
  • Unspecified
  • Week (ws)
  • Year (ys)
  • k
  • km/h
  • m/h
  • m/s
  • mCores
resolutionInMillisUTCinteger

The resolution of data points.

aggregationTypestring

The type of data points aggregation.

The element can hold these values
  • AVG
  • COUNT
  • MAX
  • MEDIAN
  • MIN
  • PERCENTILE
  • SUM
entitiesobject

The list of entities where the data points originate.

A JSON object that maps the entity ID in Dynatrace and the actual name of the entity.

Response body JSON model

json
{ "timeseriesId": "com.dynatrace.builtin:host.cpu.idle", "displayName": "CPU idle", "dimensions": [ "HOST" ], "aggregationTypes": [ "AVG", "SUM", "MIN", "MAX" ], "unit": "Percent", "filter": "BUILTIN", "detailedSource": "Infrastructure", "types": [], "dataResult": { "dataPoints": { "HOST-0000000000000007": [ [ 1522220334000, 89 ] ] }, "timeseriesId": "com.dynatrace.builtin:host.cpu.idle", "unit": "Percent", "entities": { "HOST-0000000000000007": "Laptop-8" }, "resolutionInMillisUTC": 300000, "aggregationType": "AVG" } }

Example

In this example, the request asks for the definition of the Actions per session (com.dynatrace.builtin:app.actionspersession) metric.

The API token is passed in the Authorization header.

Curl

bash
curl -X GET \ https://mySampleEnv.live.dynatrace.com/api/v1/timeseries/com.dynatrace.builtin:app.actionspersession?includeData=false \ -H 'Authorization: Api-Token dt0c01.abc123.abcdefjhij1234567890'

Request URL

plaintext
https://mySampleEnv.live.dynatrace.com/api/v1/timeseries/com.dynatrace.builtin:app.actionspersession?includeData=false

Response content

json
{ "timeseriesId": "com.dynatrace.builtin:app.actionspersession", "displayName": "Actions per session", "dimensions": [ "APPLICATION" ], "unit": "PerMinute (count/min)", "detailedSource": "Web application", "types": [], "aggregationTypes": [ "AVG" ], "filter": "BUILTIN" }

Response code

200

Related topics
  • Extend metric observability

    Learn how to extend metric observability in Dynatrace.