--- title: Update a tag configuration description: Datadog, the leading service for cloud-scale monitoring. breadcrumbs: Docs > API Reference > Metrics --- # Update a tag configuration{% #update-a-tag-configuration %} Copy pageCopied {% tab title="v2" %} | Datadog site | API endpoint | | ----------------- | --------------------------------------------------------------------- | | ap1.datadoghq.com | PATCH https://api.ap1.datadoghq.com/api/v2/metrics/{metric_name}/tags | | ap2.datadoghq.com | PATCH https://api.ap2.datadoghq.com/api/v2/metrics/{metric_name}/tags | | app.datadoghq.eu | PATCH https://api.datadoghq.eu/api/v2/metrics/{metric_name}/tags | | app.ddog-gov.com | PATCH https://api.ddog-gov.com/api/v2/metrics/{metric_name}/tags | | us2.ddog-gov.com | PATCH https://api.us2.ddog-gov.com/api/v2/metrics/{metric_name}/tags | | app.datadoghq.com | PATCH https://api.datadoghq.com/api/v2/metrics/{metric_name}/tags | | us3.datadoghq.com | PATCH https://api.us3.datadoghq.com/api/v2/metrics/{metric_name}/tags | | us5.datadoghq.com | PATCH https://api.us5.datadoghq.com/api/v2/metrics/{metric_name}/tags | ### Overview Update the tag configuration of a metric or percentile aggregations of a distribution metric or custom aggregations of a count, rate, or gauge metric. By setting `exclude_tags_mode` to true the behavior is changed from an allow-list to a deny-list, and tags in the defined list will not be queryable. Can only be used with application keys from users with the `Manage Tags for Metrics` permission. This endpoint requires a tag configuration to be created first. This endpoint requires the `metric_tags_write` permission. ### Arguments #### Path Parameters | Name | Type | Description | | ----------------------------- | ------ | ----------------------- | | metric_name [*required*] | string | The name of the metric. | ### Request #### Body Data (required) {% tab title="Model" %} | Parent field | Field | Type | Description | | ------------ | ----------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | data [*required*] | object | Object for a single tag configuration to be edited. | | data | attributes | object | Object containing the definition of a metric tag configuration to be updated. | | 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 | 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/exclude percentiles for a distribution metric. Defaults to false. Can only be applied to metrics that have a `metric_type` of `distribution`. | | attributes | tags | [string] | A list of tag keys that will be queryable for your metric. | | data | id [*required*] | string | The metric name for this resource. | | data | type [*required*] | enum | The metric tag configuration resource type. Allowed enum values: `manage_tags` | {% /tab %} {% tab title="Example" %} ```json { "data": { "type": "manage_tags", "id": "test.metric.latency", "attributes": { "tags": [ "app" ] } } } ``` {% /tab %} ### Response {% tab title="200" %} OK {% tab title="Model" %} Response object which includes a single metric's tag configuration. | Parent field | Field | Type | Description | | ------------ | ----------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | data | object | Object for a single metric tag configuration. | | data | 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` | | attributes | modified_at | date-time | Timestamp when the tag configuration was last modified. | | attributes | tags | [string] | List of tag keys on which to group. | | data | id | string | The metric name for this resource. | | data | type | enum | The metric tag configuration resource type. Allowed enum values: `manage_tags` | {% /tab %} {% tab title="Example" %} ```json { "data": { "attributes": { "aggregations": [ { "space": "sum", "time": "sum" } ], "created_at": "2020-03-25T09:48:37.463835Z", "exclude_tags_mode": false, "include_percentiles": true, "metric_type": "count", "modified_at": "2020-03-25T09:48:37.463835Z", "tags": [ "app", "datacenter" ] }, "id": "test.metric.latency", "type": "manage_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="422" %} Unprocessable Entity {% 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 # \# Path parameters export metric_name="dist.http.endpoint.request" \# Curl command curl -X PATCH "https://api.datadoghq.com/api/v2/metrics/${metric_name}/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": { "group_by": [ "app", "datacenter" ], "include_percentiles": false }, "id": "http.endpoint.request", "type": "manage_tags" } } EOF ##### ```go // Update a tag configuration returns "OK" 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 "metric_tag_configuration" in the system MetricTagConfigurationDataID := os.Getenv("METRIC_TAG_CONFIGURATION_DATA_ID") body := datadogV2.MetricTagConfigurationUpdateRequest{ Data: datadogV2.MetricTagConfigurationUpdateData{ Type: datadogV2.METRICTAGCONFIGURATIONTYPE_MANAGE_TAGS, Id: MetricTagConfigurationDataID, Attributes: &datadogV2.MetricTagConfigurationUpdateAttributes{ Tags: []string{ "app", }, }, }, } ctx := datadog.NewDefaultContext(context.Background()) configuration := datadog.NewConfiguration() apiClient := datadog.NewAPIClient(configuration) api := datadogV2.NewMetricsApi(apiClient) resp, r, err := api.UpdateTagConfiguration(ctx, MetricTagConfigurationDataID, body) if err != nil { fmt.Fprintf(os.Stderr, "Error when calling `MetricsApi.UpdateTagConfiguration`: %v\n", err) fmt.Fprintf(os.Stderr, "Full HTTP response: %v\n", r) } responseContent, _ := json.MarshalIndent(resp, "", " ") fmt.Fprintf(os.Stdout, "Response from `MetricsApi.UpdateTagConfiguration`:\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 // Update a tag configuration returns "OK" 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.MetricTagConfigurationResponse; import com.datadog.api.client.v2.model.MetricTagConfigurationType; import com.datadog.api.client.v2.model.MetricTagConfigurationUpdateAttributes; import com.datadog.api.client.v2.model.MetricTagConfigurationUpdateData; import com.datadog.api.client.v2.model.MetricTagConfigurationUpdateRequest; 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 "metric_tag_configuration" in the system String METRIC_TAG_CONFIGURATION_DATA_ID = System.getenv("METRIC_TAG_CONFIGURATION_DATA_ID"); MetricTagConfigurationUpdateRequest body = new MetricTagConfigurationUpdateRequest() .data( new MetricTagConfigurationUpdateData() .type(MetricTagConfigurationType.MANAGE_TAGS) .id(METRIC_TAG_CONFIGURATION_DATA_ID) .attributes( new MetricTagConfigurationUpdateAttributes() .tags(Collections.singletonList("app")))); try { MetricTagConfigurationResponse result = apiInstance.updateTagConfiguration(METRIC_TAG_CONFIGURATION_DATA_ID, body); System.out.println(result); } catch (ApiException e) { System.err.println("Exception when calling MetricsApi#updateTagConfiguration"); 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 """ Update a tag configuration returns "OK" 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_tag_configuration_type import MetricTagConfigurationType from datadog_api_client.v2.model.metric_tag_configuration_update_attributes import ( MetricTagConfigurationUpdateAttributes, ) from datadog_api_client.v2.model.metric_tag_configuration_update_data import MetricTagConfigurationUpdateData from datadog_api_client.v2.model.metric_tag_configuration_update_request import MetricTagConfigurationUpdateRequest # there is a valid "metric_tag_configuration" in the system METRIC_TAG_CONFIGURATION_DATA_ID = environ["METRIC_TAG_CONFIGURATION_DATA_ID"] body = MetricTagConfigurationUpdateRequest( data=MetricTagConfigurationUpdateData( type=MetricTagConfigurationType.MANAGE_TAGS, id=METRIC_TAG_CONFIGURATION_DATA_ID, attributes=MetricTagConfigurationUpdateAttributes( tags=[ "app", ], ), ), ) configuration = Configuration() with ApiClient(configuration) as api_client: api_instance = MetricsApi(api_client) response = api_instance.update_tag_configuration(metric_name=METRIC_TAG_CONFIGURATION_DATA_ID, 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 # Update a tag configuration returns "OK" response require "datadog_api_client" api_instance = DatadogAPIClient::V2::MetricsAPI.new # there is a valid "metric_tag_configuration" in the system METRIC_TAG_CONFIGURATION_DATA_ID = ENV["METRIC_TAG_CONFIGURATION_DATA_ID"] body = DatadogAPIClient::V2::MetricTagConfigurationUpdateRequest.new({ data: DatadogAPIClient::V2::MetricTagConfigurationUpdateData.new({ type: DatadogAPIClient::V2::MetricTagConfigurationType::MANAGE_TAGS, id: METRIC_TAG_CONFIGURATION_DATA_ID, attributes: DatadogAPIClient::V2::MetricTagConfigurationUpdateAttributes.new({ tags: [ "app", ], }), }), }) p api_instance.update_tag_configuration(METRIC_TAG_CONFIGURATION_DATA_ID, 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 // Update a tag configuration returns "OK" response use datadog_api_client::datadog; use datadog_api_client::datadogV2::api_metrics::MetricsAPI; use datadog_api_client::datadogV2::model::MetricTagConfigurationType; use datadog_api_client::datadogV2::model::MetricTagConfigurationUpdateAttributes; use datadog_api_client::datadogV2::model::MetricTagConfigurationUpdateData; use datadog_api_client::datadogV2::model::MetricTagConfigurationUpdateRequest; #[tokio::main] async fn main() { // there is a valid "metric_tag_configuration" in the system let metric_tag_configuration_data_id = std::env::var("METRIC_TAG_CONFIGURATION_DATA_ID").unwrap(); let body = MetricTagConfigurationUpdateRequest::new( MetricTagConfigurationUpdateData::new( metric_tag_configuration_data_id.clone(), MetricTagConfigurationType::MANAGE_TAGS, ) .attributes(MetricTagConfigurationUpdateAttributes::new().tags(vec!["app".to_string()])), ); let configuration = datadog::Configuration::new(); let api = MetricsAPI::with_config(configuration); let resp = api .update_tag_configuration(metric_tag_configuration_data_id.clone(), 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 /** * Update a tag configuration returns "OK" response */ import { client, v2 } from "@datadog/datadog-api-client"; const configuration = client.createConfiguration(); const apiInstance = new v2.MetricsApi(configuration); // there is a valid "metric_tag_configuration" in the system const METRIC_TAG_CONFIGURATION_DATA_ID = process.env .METRIC_TAG_CONFIGURATION_DATA_ID as string; const params: v2.MetricsApiUpdateTagConfigurationRequest = { body: { data: { type: "manage_tags", id: METRIC_TAG_CONFIGURATION_DATA_ID, attributes: { tags: ["app"], }, }, }, metricName: METRIC_TAG_CONFIGURATION_DATA_ID, }; apiInstance .updateTagConfiguration(params) .then((data: v2.MetricTagConfigurationResponse) => { 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 %}