--- title: Configure tags for multiple metrics description: Datadog, the leading service for cloud-scale monitoring. breadcrumbs: Docs > API Reference > Metrics --- # Configure tags for multiple metrics{% #configure-tags-for-multiple-metrics %} {% tab title="v2" %} | Datadog site | API endpoint | | ----------------- | ------------------------------------------------------------------ | | ap1.datadoghq.com | POST https://api.ap1.datadoghq.com/api/v2/metrics/config/bulk-tags | | ap2.datadoghq.com | POST https://api.ap2.datadoghq.com/api/v2/metrics/config/bulk-tags | | app.datadoghq.eu | POST https://api.datadoghq.eu/api/v2/metrics/config/bulk-tags | | app.ddog-gov.com | POST https://api.ddog-gov.com/api/v2/metrics/config/bulk-tags | | us2.ddog-gov.com | POST https://api.us2.ddog-gov.com/api/v2/metrics/config/bulk-tags | | app.datadoghq.com | POST https://api.datadoghq.com/api/v2/metrics/config/bulk-tags | | us3.datadoghq.com | POST https://api.us3.datadoghq.com/api/v2/metrics/config/bulk-tags | | us5.datadoghq.com | POST https://api.us5.datadoghq.com/api/v2/metrics/config/bulk-tags | ### Overview Create and define a list of queryable tag keys for a set of existing count, gauge, rate, and distribution metrics. Metrics are selected by passing a metric name prefix. Use the Delete method of this API path to remove tag configurations. Results can be sent to a set of account email addresses, just like the same operation in the Datadog web app. If multiple calls include the same metric, the last configuration applied (not by submit order) is used, do not expect deterministic ordering of concurrent calls. The `exclude_tags_mode` value will set all metrics that match the prefix to the same exclusion state, metric tag configurations do not support mixed inclusion and exclusion for tags on the same metric. Can only be used with application keys of users with the `Manage Tags for Metrics` permission. This endpoint requires the `metric_tags_write` permission. ### Request #### Body Data (required) {% tab title="Model" %} | Parent field | Field | Type | Description | | ------------ | ------------------------------------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | data [*required*] | object | Request object to bulk configure tags for metrics matching the given prefix. | | data | attributes | object | Optional parameters for bulk creating metric tag configurations. | | attributes | emails | [string] | A list of account emails to notify when the configuration is applied. | | 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. | | attributes | include_actively_queried_tags_window | double | When provided, all tags that have been actively queried are configured (and, therefore, remain queryable) for each metric that matches the given prefix. Minimum value is 1 second, and maximum value is 7,776,000 seconds (90 days). | | attributes | override_existing_configurations | boolean | When set to true, the configuration overrides any existing configurations for the given metric with the new set of tags in this configuration request. If false, old configurations are kept and are merged with the set of tags in this configuration request. Defaults to true. | | attributes | tags | [string] | A list of tag names to apply to the configuration. | | data | id [*required*] | string | A text prefix to match against metric names. | | data | type [*required*] | enum | The metric bulk configure tags resource. Allowed enum values: `metric_bulk_configure_tags` | {% /tab %} {% tab title="Example" %} ```json { "data": { "attributes": { "emails": [ "string" ], "tags": [ "test", "examplemetric" ] }, "id": "system.load.1", "type": "metric_bulk_configure_tags" } } ``` {% /tab %} ### Response {% tab title="202" %} Accepted {% tab title="Model" %} Wrapper for a single bulk tag configuration status response. | Parent field | Field | Type | Description | | ------------ | ---------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | data | object | The status of a request to bulk configure metric tags. It contains the fields from the original request for reference. | | data | attributes | object | Optional attributes for the status of a bulk tag configuration request. | | attributes | emails | [string] | A list of account emails to notify when the configuration is applied. | | 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. | | attributes | status | string | The status of the request. | | attributes | tags | [string] | A list of tag names to apply to the configuration. | | data | id [*required*] | string | A text prefix to match against metric names. | | data | type [*required*] | enum | The metric bulk configure tags resource. Allowed enum values: `metric_bulk_configure_tags` | {% /tab %} {% tab title="Example" %} ```json { "data": { "attributes": { "emails": [ "sue@example.com", "bob@example.com" ], "exclude_tags_mode": false, "status": "Accepted", "tags": [ "host", "pod_name", "is_shadow" ] }, "id": "kafka.lag", "type": "metric_bulk_configure_tags" } } ``` {% /tab %} {% /tab %} {% tab title="400" %} Bad Request {% tab title="Model" %} API error response. | Field | Type | Description | | ------------------------ | -------- | ----------------- | | errors [*required*] | [string] | A list of errors. | {% /tab %} {% tab title="Example" %} ```json { "errors": [ "Bad Request" ] } ``` {% /tab %} {% /tab %} {% tab title="403" %} Forbidden {% tab title="Model" %} API error response. | Field | Type | Description | | ------------------------ | -------- | ----------------- | | errors [*required*] | [string] | A list of errors. | {% /tab %} {% tab title="Example" %} ```json { "errors": [ "Bad Request" ] } ``` {% /tab %} {% /tab %} {% tab title="404" %} Not Found {% tab title="Model" %} API error response. | Field | Type | Description | | ------------------------ | -------- | ----------------- | | errors [*required*] | [string] | A list of errors. | {% /tab %} {% tab title="Example" %} ```json { "errors": [ "Bad Request" ] } ``` {% /tab %} {% /tab %} {% tab title="429" %} Too Many Requests {% tab title="Model" %} API error response. | Field | Type | Description | | ------------------------ | -------- | ----------------- | | errors [*required*] | [string] | A list of errors. | {% /tab %} {% tab title="Example" %} ```json { "errors": [ "Bad Request" ] } ``` {% /tab %} {% /tab %} ### Code Example ##### \## default # \# Curl command curl -X POST "https://api.datadoghq.com/api/v2/metrics/config/bulk-tags" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "DD-API-KEY: ${DD_API_KEY}" \ -H "DD-APPLICATION-KEY: ${DD_APP_KEY}" \ -d @- << EOF { "data": { "attributes": { "emails": [ "sue@example.com", "bob@example.com" ], "tags": [ "host", "pod_name", "is_shadow" ] }, "id": "kafka.lag", "type": "metric_bulk_configure_tags" } } EOF ##### ```go // Configure tags for multiple metrics returns "Accepted" 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() { // there is a valid "user" in the system UserDataAttributesEmail := os.Getenv("USER_DATA_ATTRIBUTES_EMAIL") body := datadogV2.MetricBulkTagConfigCreateRequest{ Data: datadogV2.MetricBulkTagConfigCreate{ Attributes: &datadogV2.MetricBulkTagConfigCreateAttributes{ Emails: []string{ UserDataAttributesEmail, }, Tags: []string{ "test", "examplemetric", }, }, Id: "system.load.1", Type: datadogV2.METRICBULKCONFIGURETAGSTYPE_BULK_MANAGE_TAGS, }, } ctx := datadog.NewDefaultContext(context.Background()) configuration := datadog.NewConfiguration() apiClient := datadog.NewAPIClient(configuration) api := datadogV2.NewMetricsApi(apiClient) resp, r, err := api.CreateBulkTagsMetricsConfiguration(ctx, body) if err != nil { fmt.Fprintf(os.Stderr, "Error when calling `MetricsApi.CreateBulkTagsMetricsConfiguration`: %v\n", err) fmt.Fprintf(os.Stderr, "Full HTTP response: %v\n", r) } responseContent, _ := json.MarshalIndent(resp, "", " ") fmt.Fprintf(os.Stdout, "Response from `MetricsApi.CreateBulkTagsMetricsConfiguration`:\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: DD_SITE="datadoghq.com" DD_API_KEY="" DD_APP_KEY="" go run "main.go" ##### ```java // Configure tags for multiple metrics returns "Accepted" 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.MetricBulkConfigureTagsType; import com.datadog.api.client.v2.model.MetricBulkTagConfigCreate; import com.datadog.api.client.v2.model.MetricBulkTagConfigCreateAttributes; import com.datadog.api.client.v2.model.MetricBulkTagConfigCreateRequest; import com.datadog.api.client.v2.model.MetricBulkTagConfigResponse; import java.util.Arrays; import java.util.Collections; public class Example { public static void main(String[] args) { ApiClient defaultClient = ApiClient.getDefaultApiClient(); MetricsApi apiInstance = new MetricsApi(defaultClient); // there is a valid "user" in the system String USER_DATA_ATTRIBUTES_EMAIL = System.getenv("USER_DATA_ATTRIBUTES_EMAIL"); MetricBulkTagConfigCreateRequest body = new MetricBulkTagConfigCreateRequest() .data( new MetricBulkTagConfigCreate() .attributes( new MetricBulkTagConfigCreateAttributes() .emails(Collections.singletonList(USER_DATA_ATTRIBUTES_EMAIL)) .tags(Arrays.asList("test", "examplemetric"))) .id("system.load.1") .type(MetricBulkConfigureTagsType.BULK_MANAGE_TAGS)); try { MetricBulkTagConfigResponse result = apiInstance.createBulkTagsMetricsConfiguration(body); System.out.println(result); } catch (ApiException e) { System.err.println("Exception when calling MetricsApi#createBulkTagsMetricsConfiguration"); 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: DD_SITE="datadoghq.com" DD_API_KEY="" DD_APP_KEY="" java "Example.java" ##### ```python """ Configure tags for multiple metrics returns "Accepted" response """ from os import environ from datadog_api_client import ApiClient, Configuration from datadog_api_client.v2.api.metrics_api import MetricsApi from datadog_api_client.v2.model.metric_bulk_configure_tags_type import MetricBulkConfigureTagsType from datadog_api_client.v2.model.metric_bulk_tag_config_create import MetricBulkTagConfigCreate from datadog_api_client.v2.model.metric_bulk_tag_config_create_attributes import MetricBulkTagConfigCreateAttributes from datadog_api_client.v2.model.metric_bulk_tag_config_create_request import MetricBulkTagConfigCreateRequest from datadog_api_client.v2.model.metric_bulk_tag_config_email_list import MetricBulkTagConfigEmailList from datadog_api_client.v2.model.metric_bulk_tag_config_tag_name_list import MetricBulkTagConfigTagNameList # there is a valid "user" in the system USER_DATA_ATTRIBUTES_EMAIL = environ["USER_DATA_ATTRIBUTES_EMAIL"] body = MetricBulkTagConfigCreateRequest( data=MetricBulkTagConfigCreate( attributes=MetricBulkTagConfigCreateAttributes( emails=MetricBulkTagConfigEmailList( [ USER_DATA_ATTRIBUTES_EMAIL, ] ), tags=MetricBulkTagConfigTagNameList( [ "test", "examplemetric", ] ), ), id="system.load.1", type=MetricBulkConfigureTagsType.BULK_MANAGE_TAGS, ), ) configuration = Configuration() with ApiClient(configuration) as api_client: api_instance = MetricsApi(api_client) response = api_instance.create_bulk_tags_metrics_configuration(body=body) 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: DD_SITE="datadoghq.com" DD_API_KEY="" DD_APP_KEY="" python3 "example.py" ##### ```ruby # Configure tags for multiple metrics returns "Accepted" response require "datadog_api_client" api_instance = DatadogAPIClient::V2::MetricsAPI.new # there is a valid "user" in the system USER_DATA_ATTRIBUTES_EMAIL = ENV["USER_DATA_ATTRIBUTES_EMAIL"] body = DatadogAPIClient::V2::MetricBulkTagConfigCreateRequest.new({ data: DatadogAPIClient::V2::MetricBulkTagConfigCreate.new({ attributes: DatadogAPIClient::V2::MetricBulkTagConfigCreateAttributes.new({ emails: [ USER_DATA_ATTRIBUTES_EMAIL, ], tags: [ "test", "examplemetric", ], }), id: "system.load.1", type: DatadogAPIClient::V2::MetricBulkConfigureTagsType::BULK_MANAGE_TAGS, }), }) p api_instance.create_bulk_tags_metrics_configuration(body) ``` #### 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: DD_SITE="datadoghq.com" DD_API_KEY="" DD_APP_KEY="" rb "example.rb" ##### ```rust // Configure tags for multiple metrics returns "Accepted" response use datadog_api_client::datadog; use datadog_api_client::datadogV2::api_metrics::MetricsAPI; use datadog_api_client::datadogV2::model::MetricBulkConfigureTagsType; use datadog_api_client::datadogV2::model::MetricBulkTagConfigCreate; use datadog_api_client::datadogV2::model::MetricBulkTagConfigCreateAttributes; use datadog_api_client::datadogV2::model::MetricBulkTagConfigCreateRequest; #[tokio::main] async fn main() { // there is a valid "user" in the system let user_data_attributes_email = std::env::var("USER_DATA_ATTRIBUTES_EMAIL").unwrap(); let body = MetricBulkTagConfigCreateRequest::new( MetricBulkTagConfigCreate::new( "system.load.1".to_string(), MetricBulkConfigureTagsType::BULK_MANAGE_TAGS, ) .attributes( MetricBulkTagConfigCreateAttributes::new() .emails(vec![user_data_attributes_email.clone()]) .tags(vec!["test".to_string(), "examplemetric".to_string()]), ), ); let configuration = datadog::Configuration::new(); let api = MetricsAPI::with_config(configuration); let resp = api.create_bulk_tags_metrics_configuration(body).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: DD_SITE="datadoghq.com" DD_API_KEY="" DD_APP_KEY="" cargo run ##### ```typescript /** * Configure tags for multiple metrics returns "Accepted" response */ import { client, v2 } from "@datadog/datadog-api-client"; const configuration = client.createConfiguration(); const apiInstance = new v2.MetricsApi(configuration); // there is a valid "user" in the system const USER_DATA_ATTRIBUTES_EMAIL = process.env .USER_DATA_ATTRIBUTES_EMAIL as string; const params: v2.MetricsApiCreateBulkTagsMetricsConfigurationRequest = { body: { data: { attributes: { emails: [USER_DATA_ATTRIBUTES_EMAIL], tags: ["test", "examplemetric"], }, id: "system.load.1", type: "metric_bulk_configure_tags", }, }, }; apiInstance .createBulkTagsMetricsConfiguration(params) .then((data: v2.MetricBulkTagConfigResponse) => { 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: DD_SITE="datadoghq.com" DD_API_KEY="" DD_APP_KEY="" tsc "example.ts" {% /tab %}