--- title: List all metrics with volumes and query activity description: Get a list of actively reporting metrics for your organization, with optional volumes, query activity, and tag configuration filters. breadcrumbs: Docs > API > List all metrics with volumes and query activity --- > For the complete documentation index, see [llms.txt](https://docs.datadoghq.com/llms.txt). # List all metrics with volumes and query activity ## v2 (latest) | Datadog site | API endpoint | | ----------------- | ------------------------------------------------ | | app.datadoghq.com | GET https://api.datadoghq.com/api/v2/metrics | | us3.datadoghq.com | GET https://api.us3.datadoghq.com/api/v2/metrics | | us5.datadoghq.com | GET https://api.us5.datadoghq.com/api/v2/metrics | | app.datadoghq.eu | GET https://api.datadoghq.eu/api/v2/metrics | | ap1.datadoghq.com | GET https://api.ap1.datadoghq.com/api/v2/metrics | | ap2.datadoghq.com | GET https://api.ap2.datadoghq.com/api/v2/metrics | | uk1.datadoghq.com | GET https://api.uk1.datadoghq.com/api/v2/metrics | | app.ddog-gov.com | GET https://api.ddog-gov.com/api/v2/metrics | | us2.ddog-gov.com | GET https://api.us2.ddog-gov.com/api/v2/metrics | ### Overview Get a list of actively reporting metrics for your organization, with optional volumes, query activity, and tag configuration filters. When you need volumes, query activity, or tag configuration status for many metrics, use this endpoint instead of calling per-metric endpoints (such as `GET /api/v2/metrics/{metric_name}/volumes` or `GET /api/v2/metrics/{metric_name}/tags`) in a loop, which is slower and quickly reaches rate limits. This endpoint does not return the tag keys or values that a metric was submitted with. Always paginate: send `page[size]` (up to 10000; a few hundred to a few thousand is typical) and follow `meta.pagination.next_cursor` (or `links.next`) until it is null or missing. Without `page[size]` or `page[cursor]`, the response is not paginated: it returns matching metrics in one response, with no pagination metadata, up to a limit of 250,000 metrics by default (some organizations have a different limit). Metrics beyond the limit are left out without any indication. Unpaginated requests in large organizations can also be slow or time out, and clients with response-size limits may fail or truncate the response. If a request with `page[cursor]` returns `410 Gone`, the cursor has expired: restart from the first page (send `page[size]` without `page[cursor]`). - **Volumes**: `include=metric_volumes` adds the indexed and ingested volume of each metric. The volume is a fixed one-hour value and is not affected by `window[seconds]`. Volumes are not returned inside `data`: each metric with volume data has a `relationships.metric_volumes.data` reference, and the volumes themselves are returned as `metric_volumes` resources in the top-level `included` array. To join them, match `included[].id` to the `id` of `data[]` items with type `metrics`; both are the metric name. `manage_tags` items in `data` repeat the same `id`, so skip them when joining. Metrics without volume data, such as standard (non-custom) metrics, have no `metric_volumes` reference or entry. - **Top metrics by volume**: `sort=-metric_volumes.indexed_volume` together with `include=metric_volumes` and `page[size]` (for example, `page[size]=20`) returns the metrics with the highest indexed volume first. Sorting requires a paginated request. - **Volume for a family of metrics**: `filter[metrics.id]=http.request*` with `include=metric_volumes` and `page[size]` returns volumes for every metric whose name starts with `http.request` (a value whose only `*` is at the end is case-sensitive). A value without `*` matches names that contain it, ignoring case. - **Unqueried metrics**: `filter[queried]=false` with `filter[queried][window][seconds]` (for example, `2592000` for 30 days) and `page[size]` returns metrics that were not queried in that window. - **Metrics without a tag configuration**: `filter[configured]=false` with `page[size]` returns custom metrics that have no Metrics without Limits™ tag configuration. - **Metric types**: if `filter[metric_type]` is omitted, metrics of all types are returned. Examples: - Top 20 metrics by indexed volume: `GET /api/v2/metrics?include=metric_volumes&sort=-metric_volumes.indexed_volume&page[size]=20` - Metrics not queried in the last 30 days, with their volumes: `GET /api/v2/metrics?filter[queried]=false&filter[queried][window][seconds]=2592000&include=metric_volumes&page[size]=1000` - Metrics without a tag configuration: `GET /api/v2/metrics?filter[configured]=false&page[size]=1000` - Volumes for metrics whose name starts with `http.request`: `GET /api/v2/metrics?filter[metrics.id]=http.request*&include=metric_volumes&page[size]=1000` 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](https://docs.datadoghq.com/api/latest/scopes.md#metrics) to access this endpoint. ### Arguments #### Query Strings | Field | 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. If omitted, metrics of all types are returned. `distribution` also matches OpenTelemetry histograms; use `exponential_histogram` or `explicit_histogram` to return only one kind of OpenTelemetry histogram. 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. | | filter[metrics.id] | string | Only return metrics whose name matches this value. A value without `*` matches metric names that contain it, ignoring case (for example, `http.request` matches `app.HTTP.request.count`). A full metric name also matches longer names that contain it. `*` is a wildcard that can appear anywhere and more than once, and these patterns also ignore case: `*.request.count` matches names that end with `.request.count`, and `app.*.count` matches names that start with `app.` and end with `.count`. The exception is a value whose only `*` is at the end (for example, `http.request*`): it matches names that start with that text and is case-sensitive. Spaces are treated as `*`. Only one value is accepted; repeating the parameter returns `400 Bad Request`. Allowed characters are letters, digits, `_`, `.`, `*`, and spaces. An empty value is ignored. | | filter[historical_metrics] | boolean | Only return metrics that have historical metrics ingestion enabled (`true`) or not enabled (`false`). | | 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. Always send it: without `page[size]` or `page[cursor]`, the response is not paginated and is capped at 250,000 metrics by default, with no indication when results are left out. 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. An expired cursor returns `410 Gone`; restart from the first page without `page[cursor]`. | ### Response {% tabs %} {% tab label="200" %} Success {% tabs %} {% tab label="Model" %} Response object that includes metrics and metric tag configurations. | Parent field | Field | Type | Description | | ------------------ | --------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | data | [] | Array of metrics and metric tag configurations. | | data | | object | Object for a single metric. | | | id | string | The metric name for this resource. | | | relationships | object | Relationships for a metric. | | relationships | metric_volumes | object | Relationship to a metric volume included in the response. | | metric_volumes | data | object | Relationship data for a metric volume. | | data | id | string | The metric name for this resource. | | data | type | enum | The metric ingested and indexed volume type. Allowed enum values: `metric_volumes`. Default: `metric_volumes`. | | | type | enum | The metric resource type. Allowed enum values: `metrics`. Default: `metrics`. | | data | | object | Object for a single metric tag configuration. | | | attributes | object | Object containing the definition of a metric tag configuration attributes. | | attributes | aggregations | [object] | Deprecated. You no longer need to configure specific time and space aggregations for Metrics Without Limits. | | aggregations | space [*required*] | enum | A space aggregation for use in query. Allowed enum values: `avg`, `max`, `min`, `sum`. | | aggregations | time [*required*] | enum | A time aggregation for use in query. Allowed enum values: `avg`, `count`, `max`, `min`, `sum`. | | attributes | created_at | date-time | Timestamp when the tag configuration was created. | | attributes | exclude_tags_mode | boolean | When set to true, the configuration will exclude the configured tags and include any other submitted tags. When set to false, the configuration will include the configured tags and exclude any other submitted tags. Defaults to false. Requires `tags` property. | | attributes | include_percentiles | boolean | Toggle to include or exclude percentile aggregations for distribution metrics. Only present when the `metric_type` is `distribution`. | | attributes | metric_type | enum | The metric's type. Allowed enum values: `gauge`, `count`, `rate`, `distribution`. Default: `gauge`. | | attributes | modified_at | date-time | Timestamp when the tag configuration was last modified. | | attributes | tags | [string] | List of tag keys on which to group. | | | id | string | The metric name for this resource. | | | relationships | object | Relationships for a metric. | | relationships | metric_volumes | object | Relationship to a metric volume included in the response. | | metric_volumes | data | object | Relationship data for a metric volume. | | data | id | string | The metric name for this resource. | | data | type | enum | The metric ingested and indexed volume type. Allowed enum values: `metric_volumes`. Default: `metric_volumes`. | | | type | enum | The metric tag configuration resource type. Allowed enum values: `manage_tags`. Default: `manage_tags`. | | | included | [object] | Array of metric volume resources included when requested with `include=metric_volumes`. | | included | attributes | object | Object containing the definition of a metric's ingested and indexed volume. | | attributes | indexed_volume | int64 | Estimated average hourly number of indexed time series for the given metric over the last hour. For organizations on Metric Name Pricing, this represents the estimated sum of indexed data points over the last hour. | | attributes | indexed_volume_delta | int64 | Change in `indexed_volume` compared with the previous hour: the last hour's value minus the value for the hour before. Negative when volume decreased. | | attributes | ingested_volume | int64 | Estimated average hourly number of ingested time series for the given metric over the last hour. This value is `0` for metrics not configured with Metrics Without Limits. For organizations on Metric Name Pricing, this represents the estimated sum of ingested data points over the last hour. | | attributes | ingested_volume_delta | int64 | Change in `ingested_volume` compared with the previous hour: the last hour's value minus the value for the hour before. Negative when volume decreased. | | included | id | string | The metric name for this resource. | | included | type | enum | The metric ingested and indexed volume type. Allowed enum values: `metric_volumes`. Default: `metric_volumes`. | | | links | object | Pagination links. Only present if pagination query parameters were provided. | | links | first | string | Link to the first page. | | links | last | string | Link to the last page. | | links | next | string | Link to the next page. | | links | prev | string | Link to previous page. | | links | self | string | Link to current page. | | | meta | object | Response metadata object. | | meta | pagination | object | Paging attributes. Only present if pagination query parameters were provided. | | pagination | cursor | string | The cursor used to get the current results, if any. | | pagination | limit | int32 | Number of results returned | | pagination | next_cursor | string | The cursor used to get the next results, if any. | | pagination | type | enum | Type of metric pagination. Allowed enum values: `cursor_limit`. Default: `cursor_limit`. | {% /tab %} {% tab label="Example" %} ```json { "data": [ { "id": "test.metric.latency", "relationships": { "metric_volumes": { "data": { "id": "test.metric.latency", "type": "metric_volumes" } } }, "type": "metrics" } ], "included": [ { "attributes": { "indexed_volume": 10, "indexed_volume_delta": 2, "ingested_volume": 20, "ingested_volume_delta": 4 }, "id": "test.metric.latency", "type": "metric_volumes" } ], "links": { "first": "string", "last": "string", "next": "string", "prev": "string", "self": "string" }, "meta": { "pagination": { "cursor": "string", "limit": "integer", "next_cursor": "string", "type": "cursor_limit" } } } ``` {% /tab %} {% /tabs %} {% /tab %} {% tab label="400" %} Bad Request {% tabs %} {% tab label="Model" %} API error response. | Field | Type | Description | | ------------------- | -------- | ----------------- | | errors [*required*] | [string] | A list of errors. | {% /tab %} {% tab label="Example" %} ```json { "errors": [ "Bad Request" ] } ``` {% /tab %} {% /tabs %} {% /tab %} {% tab label="403" %} Forbidden {% tabs %} {% tab label="Model" %} API error response. | Field | Type | Description | | ------------------- | -------- | ----------------- | | errors [*required*] | [string] | A list of errors. | {% /tab %} {% tab label="Example" %} ```json { "errors": [ "Bad Request" ] } ``` {% /tab %} {% /tabs %} {% /tab %} {% tab label="410" %} Gone {% tabs %} {% tab label="Model" %} API error response. | Field | Type | Description | | ------------------- | -------- | ----------------- | | errors [*required*] | [string] | A list of errors. | {% /tab %} {% tab label="Example" %} ```json { "errors": [ "Bad Request" ] } ``` {% /tab %} {% /tabs %} {% /tab %} {% tab label="429" %} Too Many Requests {% tabs %} {% tab label="Model" %} API error response. | Field | Type | Description | | ------------------- | -------- | ----------------- | | errors [*required*] | [string] | A list of errors. | {% /tab %} {% tab label="Example" %} ```json { "errors": [ "Bad Request" ] } ``` {% /tab %} {% /tabs %} {% /tab %} {% /tabs %} ### Code Example {% tabs %} {% tab label="Curl" %} ```bash # Set your Datadog site and credentials export DD_SITE="datadoghq.com" # Or us3.datadoghq.com, us5.datadoghq.com, datadoghq.eu, ap1.datadoghq.com, ap2.datadoghq.com, uk1.datadoghq.com, ddog-gov.com, us2.ddog-gov.com # Use a Personal Access Token or Service Access Token export DD_BEARER_TOKEN="" curl -X GET "https://api.${DD_SITE}/api/v2/metrics" \ -H "Accept: application/json" \ -H "Authorization: Bearer ${DD_BEARER_TOKEN}" ``` {% /tab %} {% tab label="Go" %} ```go // Get a list of metrics returns "Success" response package main import ( "context" "encoding/json" "fmt" "os" "github.com/DataDog/datadog-api-client-go/v2/api/datadog" "github.com/DataDog/datadog-api-client-go/v2/api/datadogV2" ) func main() { ctx := datadog.NewDefaultContext(context.Background()) ctx = context.WithValue(ctx, datadog.ContextAccessToken, os.Getenv("DD_BEARER_TOKEN")) configuration := datadog.NewConfiguration() apiClient := datadog.NewAPIClient(configuration) api := datadogV2.NewMetricsApi(apiClient) resp, r, err := api.ListTagConfigurations(ctx, *datadogV2.NewListTagConfigurationsOptionalParameters()) if err != nil { fmt.Fprintf(os.Stderr, "Error when calling `MetricsApi.ListTagConfigurations`: %v\n", err) fmt.Fprintf(os.Stderr, "Full HTTP response: %v\n", r) } responseContent, _ := json.MarshalIndent(resp, "", " ") fmt.Fprintf(os.Stdout, "Response from `MetricsApi.ListTagConfigurations`:\n%s\n", responseContent) } ``` #### Instructions First [install the library and its dependencies](https://docs.datadoghq.com/api/latest.md?code-lang=go) and then save the example to `main.go` and run following commands: ```bash DD_SITE="datadoghq.com" DD_BEARER_TOKEN="" go run "main.go" ``` {% /tab %} {% tab label="Java" %} ```java // Get a list of metrics returns "Success" response import com.datadog.api.client.ApiClient; import com.datadog.api.client.ApiException; import com.datadog.api.client.v2.api.MetricsApi; import com.datadog.api.client.v2.model.MetricsAndMetricTagConfigurationsResponse; public class Example { public static void main(String[] args) { ApiClient defaultClient = ApiClient.getDefaultApiClient(); defaultClient.setAccessToken(System.getenv("DD_BEARER_TOKEN")); MetricsApi apiInstance = new MetricsApi(defaultClient); try { MetricsAndMetricTagConfigurationsResponse result = apiInstance.listTagConfigurations(); System.out.println(result); } catch (ApiException e) { System.err.println("Exception when calling MetricsApi#listTagConfigurations"); System.err.println("Status code: " + e.getCode()); System.err.println("Reason: " + e.getResponseBody()); System.err.println("Response headers: " + e.getResponseHeaders()); e.printStackTrace(); } } } ``` #### Instructions First [install the library and its dependencies](https://docs.datadoghq.com/api/latest.md?code-lang=java) and then save the example to `Example.java` and run following commands: ```bash DD_SITE="datadoghq.com" DD_BEARER_TOKEN="" java "Example.java" ``` {% /tab %} {% tab label="Python" %} ```python """ Get a list of metrics returns "Success" response """ from os import environ from datadog_api_client import ApiClient, Configuration from datadog_api_client.v2.api.metrics_api import MetricsApi configuration = Configuration() configuration.access_token = environ["DD_BEARER_TOKEN"] with ApiClient(configuration) as api_client: api_instance = MetricsApi(api_client) response = api_instance.list_tag_configurations() print(response) ``` #### Instructions First [install the library and its dependencies](https://docs.datadoghq.com/api/latest.md?code-lang=python) and then save the example to `example.py` and run following commands: ```bash DD_SITE="datadoghq.com" DD_BEARER_TOKEN="" python3 "example.py" ``` {% /tab %} {% tab label="Ruby" %} ```ruby # Get a list of metrics returns "Success" response require "datadog_api_client" DatadogAPIClient.configure do |config| config.access_token = ENV["DD_BEARER_TOKEN"] end api_instance = DatadogAPIClient::V2::MetricsAPI.new p api_instance.list_tag_configurations() ``` #### Instructions First [install the library and its dependencies](https://docs.datadoghq.com/api/latest.md?code-lang=ruby) and then save the example to `example.rb` and run following commands: ```bash DD_SITE="datadoghq.com" DD_BEARER_TOKEN="" ruby "example.rb" ``` {% /tab %} {% tab label="Rust" %} ```rust // Get a list of metrics returns "Success" response use datadog_api_client::datadog; use datadog_api_client::datadogV2::api_metrics::ListTagConfigurationsOptionalParams; use datadog_api_client::datadogV2::api_metrics::MetricsAPI; #[tokio::main] async fn main() { let configuration = datadog::Configuration::new(); let api = MetricsAPI::with_config(configuration); let resp = api .list_tag_configurations(ListTagConfigurationsOptionalParams::default()) .await; if let Ok(value) = resp { println!("{:#?}", value); } else { println!("{:#?}", resp.unwrap_err()); } } ``` #### Instructions First [install the library and its dependencies](https://docs.datadoghq.com/api/latest.md?code-lang=rust) and then save the example to `src/main.rs` and run following commands: ```bash DD_SITE="datadoghq.com" DD_API_KEY="" DD_APP_KEY="" cargo run ``` {% /tab %} {% tab label="TypeScript" %} ```typescript /** * Get a list of metrics returns "Success" response */ import { client, v2 } from "@datadog/datadog-api-client"; const configuration = client.createConfiguration({ authMethods: { AuthZ: { accessToken: process.env.DD_BEARER_TOKEN as string, }, }, }); const apiInstance = new v2.MetricsApi(configuration); apiInstance .listTagConfigurations() .then((data: v2.MetricsAndMetricTagConfigurationsResponse) => { console.log( "API called successfully. Returned data: " + JSON.stringify(data) ); }) .catch((error: any) => console.error(error)); ``` #### Instructions First [install the library and its dependencies](https://docs.datadoghq.com/api/latest.md?code-lang=typescript) and then save the example to `example.ts` and run following commands: ```bash DD_SITE="datadoghq.com" DD_BEARER_TOKEN="" npx tsx "example.ts" ``` {% /tab %} {% /tabs %}