Add Get Tag Cardinalities Endpoint Spec (#2644)

Co-authored-by: ci.datadog-api-spec <packages@datadoghq.com>

Author: api-clients-generation-pipeline[bot]

.generated-info

@@ -1,4 +1,4 @@
 {
-  "spec_repo_commit": "20279f4",
-  "generated": "2025-07-18 10:23:04.096"
+  "spec_repo_commit": "dc49df4",
+  "generated": "2025-07-18 13:57:41.438"
 }

.generator/schemas/v2/openapi.yaml

@@ -23189,6 +23189,61 @@ components:
             type: string
           type: array
       type: object
+    MetricTagCardinalitiesData:
+      description: A list of tag cardinalities associated with the given metric.
+      items:
+        $ref: '#/components/schemas/MetricTagCardinality'
+      type: array
+    MetricTagCardinalitiesMeta:
+      description: Response metadata object.
+      properties:
+        metric_name:
+          description: 'The name of metric for which the tag cardinalities are returned.
+
+            This matches the metric name provided in the request.
+
+            '
+          type: string
+      type: object
+    MetricTagCardinalitiesResponse:
+      description: 'Response object that includes an array of objects representing
+        the cardinality details of a metric''s tags.
+
+        '
+      properties:
+        data:
+          $ref: '#/components/schemas/MetricTagCardinalitiesData'
+        meta:
+          $ref: '#/components/schemas/MetricTagCardinalitiesMeta'
+      readOnly: true
+      type: object
+    MetricTagCardinality:
+      description: Object containing metadata and attributes related to a specific
+        tag key associated with the metric.
+      example:
+        attributes:
+          cardinality_delta: 25
+        id: http.request.latency
+        type: tag_cardinality
+      properties:
+        attributes:
+          $ref: '#/components/schemas/MetricTagCardinalityAttributes'
+        id:
+          description: The name of the tag key.
+          type: string
+        type:
+          default: tag_cardinality
+          description: This describes the endpoint action.
+          type: string
+      type: object
+    MetricTagCardinalityAttributes:
+      description: An object containing properties related to the tag key
+      properties:
+        cardinality_delta:
+          description: This describes the recent change in the tag keys cardinality
+          format: int64
+          type: integer
+      type: object
     MetricTagConfiguration:
       description: Object for a single metric tag configuration.
       example:
@@ -53610,6 +53665,50 @@ paths:
       x-permission:
         operator: OPEN
         permissions: []
+  /api/v2/metrics/{metric_name}/tag-cardinalities:
+    get:
+      description: Returns the cardinality details of tags for a specific metric.
+      operationId: GetMetricTagCardinalityDetails
+      parameters:
+      - $ref: '#/components/parameters/MetricName'
+      responses:
+        '200':
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MetricTagCardinalitiesResponse'
+          description: Success
+        '400':
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/APIErrorResponse'
+          description: Bad Request
+        '403':
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/APIErrorResponse'
+          description: Forbidden
+        '404':
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/APIErrorResponse'
+          description: Not Found
+        '429':
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/APIErrorResponse'
+          description: Too Many Requests
+      summary: Get tag key cardinality details
+      tags:
+      - Metrics
+      x-permission:
+        operator: OR
+        permissions:
+        - metrics_read
   /api/v2/metrics/{metric_name}/tags:
     delete:
       description: 'Deletes a metric''s tag configuration. Can only be used with application

docs/datadog_api_client.v2.model.rst

@@ -9881,6 +9881,34 @@ datadog\_api\_client.v2.model.metric\_suggested\_tags\_attributes module
    :members:
    :show-inheritance:
 
+datadog\_api\_client.v2.model.metric\_tag\_cardinalities\_meta module
+---------------------------------------------------------------------
+
+.. automodule:: datadog_api_client.v2.model.metric_tag_cardinalities_meta
+   :members:
+   :show-inheritance:
+
+datadog\_api\_client.v2.model.metric\_tag\_cardinalities\_response module
+-------------------------------------------------------------------------
+
+.. automodule:: datadog_api_client.v2.model.metric_tag_cardinalities_response
+   :members:
+   :show-inheritance:
+
+datadog\_api\_client.v2.model.metric\_tag\_cardinality module
+-------------------------------------------------------------
+
+.. automodule:: datadog_api_client.v2.model.metric_tag_cardinality
+   :members:
+   :show-inheritance:
+
+datadog\_api\_client.v2.model.metric\_tag\_cardinality\_attributes module
+-------------------------------------------------------------------------
+
+.. automodule:: datadog_api_client.v2.model.metric_tag_cardinality_attributes
+   :members:
+   :show-inheritance:
+
 datadog\_api\_client.v2.model.metric\_tag\_configuration module
 ---------------------------------------------------------------
 

examples/v2/metrics/GetMetricTagCardinalityDetails.py

@@ -0,0 +1,15 @@
+"""
+Get tag key cardinality details 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.get_metric_tag_cardinality_details(
+        metric_name="metric_name",
+    )
+
+    print(response)

src/datadog_api_client/v2/api/metrics_api.py

@@ -30,6 +30,7 @@
 from datadog_api_client.v2.model.metric_all_tags_response import MetricAllTagsResponse
 from datadog_api_client.v2.model.metric_assets_response import MetricAssetsResponse
 from datadog_api_client.v2.model.metric_estimate_response import MetricEstimateResponse
+from datadog_api_client.v2.model.metric_tag_cardinalities_response import MetricTagCardinalitiesResponse
 from datadog_api_client.v2.model.metric_tag_configuration_response import MetricTagConfigurationResponse
 from datadog_api_client.v2.model.metric_tag_configuration_update_request import MetricTagConfigurationUpdateRequest
 from datadog_api_client.v2.model.metric_tag_configuration_create_request import MetricTagConfigurationCreateRequest
@@ -214,6 +215,29 @@ def __init__(self, api_client=None):
             api_client=api_client,
         )
 
+        self._get_metric_tag_cardinality_details_endpoint = _Endpoint(
+            settings={
+                "response_type": (MetricTagCardinalitiesResponse,),
+                "auth": ["apiKeyAuth", "appKeyAuth"],
+                "endpoint_path": "/api/v2/metrics/{metric_name}/tag-cardinalities",
+                "operation_id": "get_metric_tag_cardinality_details",
+                "http_method": "GET",
+                "version": "v2",
+            },
+            params_map={
+                "metric_name": {
+                    "required": True,
+                    "openapi_types": (str,),
+                    "attribute": "metric_name",
+                    "location": "path",
+                },
+            },
+            headers_map={
+                "accept": ["application/json"],
+            },
+            api_client=api_client,
+        )
+
         self._list_active_metric_configurations_endpoint = _Endpoint(
             settings={
                 "response_type": (MetricSuggestedTagsAndAggregationsResponse,),
@@ -628,6 +652,23 @@ def estimate_metrics_output_series(
 
         return self._estimate_metrics_output_series_endpoint.call_with_http_info(**kwargs)
 
+    def get_metric_tag_cardinality_details(
+        self,
+        metric_name: str,
+    ) -> MetricTagCardinalitiesResponse:
+        """Get tag key cardinality details.
+
+        Returns the cardinality details of tags for a specific metric.
+
+        :param metric_name: The name of the metric.
+        :type metric_name: str
+        :rtype: MetricTagCardinalitiesResponse
+        """
+        kwargs: Dict[str, Any] = {}
+        kwargs["metric_name"] = metric_name
+
+        return self._get_metric_tag_cardinality_details_endpoint.call_with_http_info(**kwargs)
+
     def list_active_metric_configurations(
         self,
         metric_name: str,

src/datadog_api_client/v2/model/metric_tag_cardinalities_meta.py

@@ -0,0 +1,37 @@
+# Unless explicitly stated otherwise all files in this repository are licensed under the Apache-2.0 License.
+# This product includes software developed at Datadog (https://www.datadoghq.com/).
+# Copyright 2019-Present Datadog, Inc.
+from __future__ import annotations
+
+from typing import Union
+
+from datadog_api_client.model_utils import (
+    ModelNormal,
+    cached_property,
+    unset,
+    UnsetType,
+)
+
+
+class MetricTagCardinalitiesMeta(ModelNormal):
+    @cached_property
+    def openapi_types(_):
+        return {
+            "metric_name": (str,),
+        }
+
+    attribute_map = {
+        "metric_name": "metric_name",
+    }
+
+    def __init__(self_, metric_name: Union[str, UnsetType] = unset, **kwargs):
+        """
+        Response metadata object.
+
+        :param metric_name: The name of metric for which the tag cardinalities are returned.
+            This matches the metric name provided in the request.
+        :type metric_name: str, optional
+        """
+        if metric_name is not unset:
+            kwargs["metric_name"] = metric_name
+        super().__init__(kwargs)

src/datadog_api_client/v2/model/metric_tag_cardinalities_response.py

@@ -0,0 +1,56 @@
+# Unless explicitly stated otherwise all files in this repository are licensed under the Apache-2.0 License.
+# This product includes software developed at Datadog (https://www.datadoghq.com/).
+# Copyright 2019-Present Datadog, Inc.
+from __future__ import annotations
+
+from typing import List, Union, TYPE_CHECKING
+
+from datadog_api_client.model_utils import (
+    ModelNormal,
+    cached_property,
+    unset,
+    UnsetType,
+)
+
+
+if TYPE_CHECKING:
+    from datadog_api_client.v2.model.metric_tag_cardinality import MetricTagCardinality
+    from datadog_api_client.v2.model.metric_tag_cardinalities_meta import MetricTagCardinalitiesMeta
+
+
+class MetricTagCardinalitiesResponse(ModelNormal):
+    @cached_property
+    def openapi_types(_):
+        from datadog_api_client.v2.model.metric_tag_cardinality import MetricTagCardinality
+        from datadog_api_client.v2.model.metric_tag_cardinalities_meta import MetricTagCardinalitiesMeta
+
+        return {
+            "data": ([MetricTagCardinality],),
+            "meta": (MetricTagCardinalitiesMeta,),
+        }
+
+    attribute_map = {
+        "data": "data",
+        "meta": "meta",
+    }
+
+    def __init__(
+        self_,
+        data: Union[List[MetricTagCardinality], UnsetType] = unset,
+        meta: Union[MetricTagCardinalitiesMeta, UnsetType] = unset,
+        **kwargs,
+    ):
+        """
+        Response object that includes an array of objects representing the cardinality details of a metric's tags.
+
+        :param data: A list of tag cardinalities associated with the given metric.
+        :type data: [MetricTagCardinality], optional
+
+        :param meta: Response metadata object.
+        :type meta: MetricTagCardinalitiesMeta, optional
+        """
+        if data is not unset:
+            kwargs["data"] = data
+        if meta is not unset:
+            kwargs["meta"] = meta
+        super().__init__(kwargs)

src/datadog_api_client/v2/model/metric_tag_cardinality.py

@@ -0,0 +1,62 @@
+# Unless explicitly stated otherwise all files in this repository are licensed under the Apache-2.0 License.
+# This product includes software developed at Datadog (https://www.datadoghq.com/).
+# Copyright 2019-Present Datadog, Inc.
+from __future__ import annotations
+
+from typing import Union, TYPE_CHECKING
+
+from datadog_api_client.model_utils import (
+    ModelNormal,
+    cached_property,
+    unset,
+    UnsetType,
+)
+
+
+if TYPE_CHECKING:
+    from datadog_api_client.v2.model.metric_tag_cardinality_attributes import MetricTagCardinalityAttributes
+
+
+class MetricTagCardinality(ModelNormal):
+    @cached_property
+    def openapi_types(_):
+        from datadog_api_client.v2.model.metric_tag_cardinality_attributes import MetricTagCardinalityAttributes
+
+        return {
+            "attributes": (MetricTagCardinalityAttributes,),
+            "id": (str,),
+            "type": (str,),
+        }
+
+    attribute_map = {
+        "attributes": "attributes",
+        "id": "id",
+        "type": "type",
+    }
+
+    def __init__(
+        self_,
+        attributes: Union[MetricTagCardinalityAttributes, UnsetType] = unset,
+        id: Union[str, UnsetType] = unset,
+        type: Union[str, UnsetType] = unset,
+        **kwargs,
+    ):
+        """
+        Object containing metadata and attributes related to a specific tag key associated with the metric.
+
+        :param attributes: An object containing properties related to the tag key
+        :type attributes: MetricTagCardinalityAttributes, optional
+
+        :param id: The name of the tag key.
+        :type id: str, optional
+
+        :param type: This describes the endpoint action.
+        :type type: str, optional
+        """
+        if attributes is not unset:
+            kwargs["attributes"] = attributes
+        if id is not unset:
+            kwargs["id"] = id
+        if type is not unset:
+            kwargs["type"] = type
+        super().__init__(kwargs)