Get a list of metrics

GET https://api.ap1.datadoghq.com/api/v2/metricshttps://api.ap2.datadoghq.com/api/v2/metricshttps://api.datadoghq.eu/api/v2/metricshttps://api.ddog-gov.com/api/v2/metricshttps://api.us2.ddog-gov.com/api/v2/metricshttps://api.datadoghq.com/api/v2/metricshttps://api.us3.datadoghq.com/api/v2/metricshttps://api.us5.datadoghq.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 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.
Allowed enum values: non_distribution, distribution

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

This parameter has no effect unless filter[queried] is also set. Only return metrics that have been queried or not queried in the specified window. 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 1 second. For example: filter[queried]=true&filter[queried][window][seconds]=604800.

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.

window[seconds]

integer

Only return metrics that have been actively reporting in the specified window. The default value is 3600 seconds (1 hour), the maximum value is 2,592,000 seconds (30 days), and the minimum value is 1 second.

page[size]

integer

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

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.

Expand All

Field

Type

Description

data

[ <oneOf>]

Array of metrics and metric tag configurations.

Option 1

object

Object for a single metric tag configuration.

id

string

The metric name for this resource.

type

enum

The metric resource type. Allowed enum values: metrics

default: metrics

Option 2

object

Object for a single metric tag configuration.

attributes

object

Object containing the definition of a metric tag configuration attributes.

aggregations

[object]

Deprecated. You no longer need to configure specific time and space aggregations for Metrics Without Limits.

space [required]

enum

A space aggregation for use in query. Allowed enum values: avg,max,min,sum

time [required]

enum

A time aggregation for use in query. Allowed enum values: avg,count,max,min,sum

created_at

date-time

Timestamp when the tag configuration was created.

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.

include_percentiles

boolean

Toggle to include or exclude percentile aggregations for distribution metrics. Only present when the metric_type is distribution.

metric_type

enum

The metric's type. Allowed enum values: gauge,count,rate,distribution

default: gauge

modified_at

date-time

Timestamp when the tag configuration was last modified.

tags

[string]

List of tag keys on which to group.

id

string

The metric name for this resource.

type

enum

The metric tag configuration resource type. Allowed enum values: manage_tags

default: manage_tags

links

object

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

first

string

Link to the first page.

last

string

Link to the last page.

next

string

Link to the next page.

prev

string

Link to previous page.

self

string

Link to current page.

meta

object

Response metadata object.

pagination

object

Paging attributes. Only present if pagination query parameters were provided.

cursor

string

The cursor used to get the current results, if any.

limit

int32

Number of results returned

next_cursor

string

The cursor used to get the next results, if any.

type

enum

Type of metric pagination. Allowed enum values: cursor_limit

default: cursor_limit

{
  "data": [
    {
      "id": "test.metric.latency",
      "type": "metrics"
    }
  ],
  "links": {
    "first": "string",
    "last": "string",
    "next": "string",
    "prev": "string",
    "self": "string"
  },
  "meta": {
    "pagination": {
      "cursor": "string",
      "limit": "integer",
      "next_cursor": "string",
      "type": "cursor_limit"
    }
  }
}

Bad Request

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Forbidden

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Too Many Requests

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Code Example

                  # Curl command
curl -X GET "https://api.ap1.datadoghq.com"https://api.ap2.datadoghq.com"https://api.datadoghq.eu"https://api.ddog-gov.com"https://api.us2.ddog-gov.com"https://api.datadoghq.com"https://api.us3.datadoghq.com"https://api.us5.datadoghq.com/api/v2/metrics" \ -H "Accept: application/json" \ -H "DD-API-KEY: ${DD_API_KEY}" \ -H "DD-APPLICATION-KEY: ${DD_APP_KEY}"
"""
Get a list of metrics returns "Success" response
"""

from datadog_api_client import ApiClient, Configuration
from datadog_api_client.v2.api.metrics_api import MetricsApi

configuration = Configuration()
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 and then save the example to example.py and run following commands:

    
DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comap2.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_API_KEY="<DD_API_KEY>" DD_APP_KEY="<DD_APP_KEY>" python3 "example.py"
# Get a list of metrics returns "Success" response

require "datadog_api_client"
api_instance = DatadogAPIClient::V2::MetricsAPI.new
p api_instance.list_tag_configurations()

Instructions

First install the library and its dependencies and then save the example to example.rb and run following commands:

    
DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comap2.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_API_KEY="<DD_API_KEY>" DD_APP_KEY="<DD_APP_KEY>" rb "example.rb"
// 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())
	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 and then save the example to main.go and run following commands:

    
DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comap2.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_API_KEY="<DD_API_KEY>" DD_APP_KEY="<DD_APP_KEY>" go run "main.go"
// 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();
    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 and then save the example to Example.java and run following commands:

    
DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comap2.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_API_KEY="<DD_API_KEY>" DD_APP_KEY="<DD_APP_KEY>" java "Example.java"
// 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 and then save the example to src/main.rs and run following commands:

    
DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comap2.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_API_KEY="<DD_API_KEY>" DD_APP_KEY="<DD_APP_KEY>" cargo run
/**
 * Get a list of metrics returns "Success" response
 */

import { client, v2 } from "@datadog/datadog-api-client";

const configuration = client.createConfiguration();
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 and then save the example to example.ts and run following commands:

    
DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comap2.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_API_KEY="<DD_API_KEY>" DD_APP_KEY="<DD_APP_KEY>" tsc "example.ts"