For AI agents: A markdown version of this page is available at https://dnd37xeb23o8n.cloudfront.net/jen.gilbert/astro-base/api/latest/metrics/get-a-list-of-metrics.md. A documentation index is available at /llms.txt.
homeHomedocsDocsapiAPI
Language
Datadog site

Get a list of metrics

GEThttps://api.datadoghq.com/api/v2/metricshttps://api.us3.datadoghq.com/api/v2/metricshttps://api.us5.datadoghq.com/api/v2/metricshttps://api.datadoghq.eu/api/v2/metricshttps://api.ap1.datadoghq.com/api/v2/metricshttps://api.ap2.datadoghq.com/api/v2/metricshttps://api.uk1.datadoghq.com/api/v2/metricshttps://api.ddog-gov.com/api/v2/metricshttps://api.us2.ddog-gov.com/api/v2/metrics

Overview

Get a list of actively reporting metrics for your organization. Pagination is optional using the page[cursor] and page[size] query parameters.

Query parameters use bracket notation (for example, filter[tags], filter[queried][window][seconds]). Pass them as standard URL query strings, URL-encoding the brackets if your client does not handle them. For example: GET /api/v2/metrics?filter[tags]=env:prod&window[seconds]=86400&page[size]=500.

This endpoint requires the metrics_read permission.

OAuth apps require the metrics_read authorization scope to access this endpoint.

Arguments

Query Strings

Name
Type
Description
filter[configured]
boolean

Only return custom metrics that have been configured (true) or not configured (false) with Metrics Without Limits.

filter[is_configurable]
boolean

Only return metrics that are eligible (true) or ineligible (false) for configuration with Metrics Without Limits.

filter[tags_configured]
string

Only return metrics that have the given tag key(s) in their Metrics Without Limits configuration (included or excluded).

filter[metric_type]
enum

Only return metrics of the given metric type.

Default: distribution
Allowed enum values: non_distribution, distribution, exponential_histogram, explicit_histogram
filter[include_percentiles]
boolean

Only return distribution metrics that have percentile aggregations enabled (true) or disabled (false).

filter[queried]
boolean

Only return metrics that have been queried (true) or not queried (false) in the look back window. Set the window with filter[queried][window][seconds]; if omitted, a default window is used.

filter[queried][window][seconds]
integer

The look-back window for filter[queried], in seconds. You must also set filter[queried], or the request returns a 400 error. The default value is 2,592,000 seconds (30 days), the maximum value is 15,552,000 seconds (180 days), and the minimum value is 0. With 0, the window ends now, so filter[queried]=true returns almost no metrics and filter[queried]=false returns all metrics. For example: filter[queried]=true&filter[queried][window][seconds]=604800.

Default: 2592000
filter[tags]
string

Only return metrics that were submitted with tags matching this expression. You can use AND, OR, IN, and wildcards. For example: filter[tags]=env IN (staging,test) AND service:web*.

filter[related_assets]
boolean

Only return metrics that are used in at least one dashboard, monitor, notebook, or SLO.

include
string

Include related resources in the response. Set to metric_volumes to include indexed and ingested volume counts for each metric.

sort
string

Sort results by metric volume. Prefix a key with - for descending order. Supported keys: metric_volumes.indexed_volume, metric_volumes.ingested_volume, metric_volumes.indexed_volume_delta, metric_volumes.ingested_volume_delta. Requires a paginated request (page[size] or page[cursor]).

window[seconds]
integer

Only return metrics that have been actively reporting in this window. The default value is 3,600 seconds (1 hour), the maximum value is 5,184,000 seconds (60 days), and the minimum value is 0. With 0, the API returns only metrics that reported in the last few minutes.

Default: 3600
page[size]
integer

Maximum number of results per page. Send page[size] on the first request to opt in to pagination. On subsequent requests, send page[cursor] set to the value of meta.pagination.next_cursor from the previous response. To retain a custom page size, include page[size] on every request. The default value is 10000, the maximum value is 10000, and the minimum value is 1.

Default: 10000
page[cursor]
string

Cursor for pagination. Use page[size] to opt-in to pagination and get the first page; for subsequent pages, use the value from meta.pagination.next_cursor in the response. Pagination is complete when next_cursor is null.

Response

Success

Response object that includes metrics and metric tag configurations.

Field
Type
Description
data
[<oneOf>]

Array of metrics and metric tag configurations.

included
[object]

Array of metric volume resources included when requested with include=metric_volumes.

links
object

Pagination links. Only present if pagination query parameters were provided.

meta
object

Response metadata object.

Code Example

Get a list of metrics
# Set your Datadog site and credentials
export DD_SITE="datadoghq.com"
# Use a Personal Access Token or Service Access Token
export DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>"

curl -X GET "https://api.${DD_SITE}/api/v2/metrics" \
-H "Accept: application/json" \
-H "Authorization: Bearer ${DD_BEARER_TOKEN}"
# Set your Datadog site and credentials
export DD_SITE="us3.datadoghq.com"
# Use a Personal Access Token or Service Access Token
export DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>"

curl -X GET "https://api.${DD_SITE}/api/v2/metrics" \
-H "Accept: application/json" \
-H "Authorization: Bearer ${DD_BEARER_TOKEN}"
# Set your Datadog site and credentials
export DD_SITE="us5.datadoghq.com"
# Use a Personal Access Token or Service Access Token
export DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>"

curl -X GET "https://api.${DD_SITE}/api/v2/metrics" \
-H "Accept: application/json" \
-H "Authorization: Bearer ${DD_BEARER_TOKEN}"
# Set your Datadog site and credentials
export DD_SITE="datadoghq.eu"
# Use a Personal Access Token or Service Access Token
export DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>"

curl -X GET "https://api.${DD_SITE}/api/v2/metrics" \
-H "Accept: application/json" \
-H "Authorization: Bearer ${DD_BEARER_TOKEN}"
# Set your Datadog site and credentials
export DD_SITE="ap1.datadoghq.com"
# Use a Personal Access Token or Service Access Token
export DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>"

curl -X GET "https://api.${DD_SITE}/api/v2/metrics" \
-H "Accept: application/json" \
-H "Authorization: Bearer ${DD_BEARER_TOKEN}"
# Set your Datadog site and credentials
export DD_SITE="ap2.datadoghq.com"
# Use a Personal Access Token or Service Access Token
export DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>"

curl -X GET "https://api.${DD_SITE}/api/v2/metrics" \
-H "Accept: application/json" \
-H "Authorization: Bearer ${DD_BEARER_TOKEN}"
# Set your Datadog site and credentials
export DD_SITE="uk1.datadoghq.com"
# Use a Personal Access Token or Service Access Token
export DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>"

curl -X GET "https://api.${DD_SITE}/api/v2/metrics" \
-H "Accept: application/json" \
-H "Authorization: Bearer ${DD_BEARER_TOKEN}"
# Set your Datadog site and credentials
export DD_SITE="ddog-gov.com"
# Use a Personal Access Token or Service Access Token
export DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>"

curl -X GET "https://api.${DD_SITE}/api/v2/metrics" \
-H "Accept: application/json" \
-H "Authorization: Bearer ${DD_BEARER_TOKEN}"
# Set your Datadog site and credentials
export DD_SITE="us2.ddog-gov.com"
# Use a Personal Access Token or Service Access Token
export DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>"

curl -X GET "https://api.${DD_SITE}/api/v2/metrics" \
-H "Accept: application/json" \
-H "Authorization: Bearer ${DD_BEARER_TOKEN}"