tag_descriptions

Creates, updates, deletes, gets or lists a tag_descriptions resource.

Overview

Name	tag_descriptions
Type	Resource
Id	datadog.cloud_costs.tag_descriptions

Fields

The following fields are returned by SELECT queries:

get_cost_tag_description_by_key

Name	Datatype	Description
id	string	Stable identifier of the tag description. Equals the tag key when the description is the cross-cloud default; encodes both the cloud and the tag key when the description is cloud-specific. (example: account_id)
attributes	object	Human-readable description and metadata attached to a Cloud Cost Management tag key, optionally scoped to a single cloud provider.
type	string	Type of the Cloud Cost Management tag description resource. (cost_tag_description) (default: cost_tag_description, example: cost_tag_description)

list_cost_tag_descriptions

Name	Datatype	Description
id	string	Stable identifier of the tag description. Equals the tag key when the description is the cross-cloud default; encodes both the cloud and the tag key when the description is cloud-specific. (example: account_id)
attributes	object	Human-readable description and metadata attached to a Cloud Cost Management tag key, optionally scoped to a single cloud provider.
type	string	Type of the Cloud Cost Management tag description resource. (cost_tag_description) (default: cost_tag_description, example: cost_tag_description)

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get_cost_tag_description_by_key	select	tag_key	filter[cloud]	Get the Cloud Cost Management description for a single tag key. Use filter[cloud] to scope the lookup to a specific cloud provider; when omitted, the response resolves the description in fallback order (cloud-specific organization override, then cloudless organization default, then Datadog's global default).
list_cost_tag_descriptions	select		filter[cloud]	List Cloud Cost Management tag key descriptions for the organization. Use filter[cloud] to scope the result to a single cloud provider; when omitted, both cross-cloud defaults and cloud-specific descriptions are returned.
upsert_cost_tag_description_by_key	replace	tag_key, data		Create or update a Cloud Cost Management tag key description. The new description and optional cloud scoping are supplied in the request body. Omit cloud to set a cross-cloud default for the tag key.
delete_cost_tag_description_by_key	delete	tag_key	cloud	Delete a Cloud Cost Management tag key description. When cloud is omitted, deletes every description for the tag key, falling back to Datadog's global default when available. When cloud is provided, deletes only the description scoped to that cloud provider.
generate_cost_tag_description_by_key	exec	tag_key		Use AI to draft a Cloud Cost Management tag key description based on associated cost data. The generated description is returned in the response and is not persisted by this endpoint; follow up with UpsertCostTagDescriptionByKey to save it.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
site	string	The Datadog site (region) for your organization, for example datadoghq.com, us3.datadoghq.com, us5.datadoghq.com, ap1.datadoghq.com, ap2.datadoghq.com, datadoghq.eu, ddog-gov.com. Resolved from the DD_SITE environment variable when set. Optional: defaults to datadoghq.com, or the value of the DD_SITE environment variable when set; a WHERE value overrides both.
tag_key	string	The tag key to generate an AI description for.
cloud	string	Cloud provider to scope the deletion to (for example, aws). Omit to delete every description for the tag key.
filter[cloud]	string	Filter descriptions to a specific cloud provider (for example, aws). Omit to return descriptions across all clouds.

SELECT examples

get_cost_tag_description_by_key

Get the Cloud Cost Management description for a single tag key. Use filter[cloud] to scope the lookup to a specific cloud provider; when omitted, the response resolves the description in fallback order (cloud-specific organization override, then cloudless organization default, then Datadog's global default).

SELECT
id,
attributes,
type
FROM datadog.cloud_costs.tag_descriptions
WHERE tag_key = '{{ tag_key }}' -- required
AND filter[cloud] = '{{ filter[cloud] }}'
;

list_cost_tag_descriptions

List Cloud Cost Management tag key descriptions for the organization. Use filter[cloud] to scope the result to a single cloud provider; when omitted, both cross-cloud defaults and cloud-specific descriptions are returned.

SELECT
id,
attributes,
type
FROM datadog.cloud_costs.tag_descriptions
WHERE filter[cloud] = '{{ filter[cloud] }}'
;

REPLACE examples

upsert_cost_tag_description_by_key

Create or update a Cloud Cost Management tag key description. The new description and optional cloud scoping are supplied in the request body. Omit cloud to set a cross-cloud default for the tag key.

REPLACE datadog.cloud_costs.tag_descriptions
SET 
data = '{{ data }}'
WHERE 
tag_key = '{{ tag_key }}' --required
AND data = '{{ data }}' --required;

DELETE examples

delete_cost_tag_description_by_key

Delete a Cloud Cost Management tag key description. When cloud is omitted, deletes every description for the tag key, falling back to Datadog's global default when available. When cloud is provided, deletes only the description scoped to that cloud provider.

DELETE FROM datadog.cloud_costs.tag_descriptions
WHERE tag_key = '{{ tag_key }}' --required
AND cloud = '{{ cloud }}'
;

Lifecycle Methods

EXEC variables use wire (API) names.

generate_cost_tag_description_by_key

Use AI to draft a Cloud Cost Management tag key description based on associated cost data. The generated description is returned in the response and is not persisted by this endpoint; follow up with UpsertCostTagDescriptionByKey to save it.

EXEC datadog.cloud_costs.tag_descriptions.generate_cost_tag_description_by_key 
@tag_key='{{ tag_key }}' --required 
;