Add Get Tag Cardinalities Endpoint Spec (#737)

Co-authored-by: ci.datadog-api-spec <[email protected]>

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

.generated-info

@@ -1,4 +1,4 @@
 {
-  "spec_repo_commit": "20279f4",
-  "generated": "2025-07-18 10:27:51.182"
+  "spec_repo_commit": "dc49df4",
+  "generated": "2025-07-18 14:02:24.862"
 }

.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

examples/v2_metrics_GetMetricTagCardinalityDetails.rs

@@ -0,0 +1,17 @@
+// Get tag key cardinality details returns "Success" response
+use datadog_api_client::datadog;
+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
+        .get_metric_tag_cardinality_details("metric_name".to_string())
+        .await;
+    if let Ok(value) = resp {
+        println!("{:#?}", value);
+    } else {
+        println!("{:#?}", resp.unwrap_err());
+    }
+}

src/datadogV2/api/api_metrics.rs

@@ -228,6 +228,14 @@ pub enum EstimateMetricsOutputSeriesError {
     UnknownValue(serde_json::Value),
 }
 
+/// GetMetricTagCardinalityDetailsError is a struct for typed errors of method [`MetricsAPI::get_metric_tag_cardinality_details`]
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(untagged)]
+pub enum GetMetricTagCardinalityDetailsError {
+    APIErrorResponse(crate::datadogV2::model::APIErrorResponse),
+    UnknownValue(serde_json::Value),
+}
+
 /// ListActiveMetricConfigurationsError is a struct for typed errors of method [`MetricsAPI::list_active_metric_configurations`]
 #[derive(Debug, Clone, Serialize, Deserialize)]
 #[serde(untagged)]
@@ -1122,6 +1130,118 @@ impl MetricsAPI {
         }
     }
 
+    /// Returns the cardinality details of tags for a specific metric.
+    pub async fn get_metric_tag_cardinality_details(
+        &self,
+        metric_name: String,
+    ) -> Result<
+        crate::datadogV2::model::MetricTagCardinalitiesResponse,
+        datadog::Error<GetMetricTagCardinalityDetailsError>,
+    > {
+        match self
+            .get_metric_tag_cardinality_details_with_http_info(metric_name)
+            .await
+        {
+            Ok(response_content) => {
+                if let Some(e) = response_content.entity {
+                    Ok(e)
+                } else {
+                    Err(datadog::Error::Serde(serde::de::Error::custom(
+                        "response content was None",
+                    )))
+                }
+            }
+            Err(err) => Err(err),
+        }
+    }
+
+    /// Returns the cardinality details of tags for a specific metric.
+    pub async fn get_metric_tag_cardinality_details_with_http_info(
+        &self,
+        metric_name: String,
+    ) -> Result<
+        datadog::ResponseContent<crate::datadogV2::model::MetricTagCardinalitiesResponse>,
+        datadog::Error<GetMetricTagCardinalityDetailsError>,
+    > {
+        let local_configuration = &self.config;
+        let operation_id = "v2.get_metric_tag_cardinality_details";
+
+        let local_client = &self.client;
+
+        let local_uri_str = format!(
+            "{}/api/v2/metrics/{metric_name}/tag-cardinalities",
+            local_configuration.get_operation_host(operation_id),
+            metric_name = datadog::urlencode(metric_name)
+        );
+        let mut local_req_builder =
+            local_client.request(reqwest::Method::GET, local_uri_str.as_str());
+
+        // build headers
+        let mut headers = HeaderMap::new();
+        headers.insert("Accept", HeaderValue::from_static("application/json"));
+
+        // build user agent
+        match HeaderValue::from_str(local_configuration.user_agent.as_str()) {
+            Ok(user_agent) => headers.insert(reqwest::header::USER_AGENT, user_agent),
+            Err(e) => {
+                log::warn!("Failed to parse user agent header: {e}, falling back to default");
+                headers.insert(
+                    reqwest::header::USER_AGENT,
+                    HeaderValue::from_static(datadog::DEFAULT_USER_AGENT.as_str()),
+                )
+            }
+        };
+
+        // build auth
+        if let Some(local_key) = local_configuration.auth_keys.get("apiKeyAuth") {
+            headers.insert(
+                "DD-API-KEY",
+                HeaderValue::from_str(local_key.key.as_str())
+                    .expect("failed to parse DD-API-KEY header"),
+            );
+        };
+        if let Some(local_key) = local_configuration.auth_keys.get("appKeyAuth") {
+            headers.insert(
+                "DD-APPLICATION-KEY",
+                HeaderValue::from_str(local_key.key.as_str())
+                    .expect("failed to parse DD-APPLICATION-KEY header"),
+            );
+        };
+
+        local_req_builder = local_req_builder.headers(headers);
+        let local_req = local_req_builder.build()?;
+        log::debug!("request content: {:?}", local_req.body());
+        let local_resp = local_client.execute(local_req).await?;
+
+        let local_status = local_resp.status();
+        let local_content = local_resp.text().await?;
+        log::debug!("response content: {}", local_content);
+
+        if !local_status.is_client_error() && !local_status.is_server_error() {
+            match serde_json::from_str::<crate::datadogV2::model::MetricTagCardinalitiesResponse>(
+                &local_content,
+            ) {
+                Ok(e) => {
+                    return Ok(datadog::ResponseContent {
+                        status: local_status,
+                        content: local_content,
+                        entity: Some(e),
+                    })
+                }
+                Err(e) => return Err(datadog::Error::Serde(e)),
+            };
+        } else {
+            let local_entity: Option<GetMetricTagCardinalityDetailsError> =
+                serde_json::from_str(&local_content).ok();
+            let local_error = datadog::ResponseContent {
+                status: local_status,
+                content: local_content,
+                entity: local_entity,
+            };
+            Err(datadog::Error::ResponseError(local_error))
+        }
+    }
+
     /// List tags and aggregations that are actively queried on dashboards, notebooks, monitors, the Metrics Explorer, and using the API for a given metric name.
     pub async fn list_active_metric_configurations(
         &self,

src/datadogV2/model/mod.rs

@@ -2596,6 +2596,14 @@ pub mod model_metric_estimate_type;
 pub use self::model_metric_estimate_type::MetricEstimateType;
 pub mod model_metric_estimate_resource_type;
 pub use self::model_metric_estimate_resource_type::MetricEstimateResourceType;
+pub mod model_metric_tag_cardinalities_response;
+pub use self::model_metric_tag_cardinalities_response::MetricTagCardinalitiesResponse;
+pub mod model_metric_tag_cardinality;
+pub use self::model_metric_tag_cardinality::MetricTagCardinality;
+pub mod model_metric_tag_cardinality_attributes;
+pub use self::model_metric_tag_cardinality_attributes::MetricTagCardinalityAttributes;
+pub mod model_metric_tag_cardinalities_meta;
+pub use self::model_metric_tag_cardinalities_meta::MetricTagCardinalitiesMeta;
 pub mod model_metric_tag_configuration_response;
 pub use self::model_metric_tag_configuration_response::MetricTagConfigurationResponse;
 pub mod model_metric_tag_configuration_update_request;

src/datadogV2/model/model_metric_tag_cardinalities_meta.rs

@@ -0,0 +1,108 @@
+// 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.
+use serde::de::{Error, MapAccess, Visitor};
+use serde::{Deserialize, Deserializer, Serialize};
+use serde_with::skip_serializing_none;
+use std::fmt::{self, Formatter};
+
+/// Response metadata object.
+#[non_exhaustive]
+#[skip_serializing_none]
+#[derive(Clone, Debug, PartialEq, Serialize)]
+pub struct MetricTagCardinalitiesMeta {
+    /// The name of metric for which the tag cardinalities are returned.
+    /// This matches the metric name provided in the request.
+    ///
+    #[serde(rename = "metric_name")]
+    pub metric_name: Option<String>,
+    #[serde(flatten)]
+    pub additional_properties: std::collections::BTreeMap<String, serde_json::Value>,
+    #[serde(skip)]
+    #[serde(default)]
+    pub(crate) _unparsed: bool,
+}
+
+impl MetricTagCardinalitiesMeta {
+    pub fn new() -> MetricTagCardinalitiesMeta {
+        MetricTagCardinalitiesMeta {
+            metric_name: None,
+            additional_properties: std::collections::BTreeMap::new(),
+            _unparsed: false,
+        }
+    }
+
+    pub fn metric_name(mut self, value: String) -> Self {
+        self.metric_name = Some(value);
+        self
+    }
+
+    pub fn additional_properties(
+        mut self,
+        value: std::collections::BTreeMap<String, serde_json::Value>,
+    ) -> Self {
+        self.additional_properties = value;
+        self
+    }
+}
+
+impl Default for MetricTagCardinalitiesMeta {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+impl<'de> Deserialize<'de> for MetricTagCardinalitiesMeta {
+    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
+    where
+        D: Deserializer<'de>,
+    {
+        struct MetricTagCardinalitiesMetaVisitor;
+        impl<'a> Visitor<'a> for MetricTagCardinalitiesMetaVisitor {
+            type Value = MetricTagCardinalitiesMeta;
+
+            fn expecting(&self, f: &mut Formatter<'_>) -> fmt::Result {
+                f.write_str("a mapping")
+            }
+
+            fn visit_map<M>(self, mut map: M) -> Result<Self::Value, M::Error>
+            where
+                M: MapAccess<'a>,
+            {
+                let mut metric_name: Option<String> = None;
+                let mut additional_properties: std::collections::BTreeMap<
+                    String,
+                    serde_json::Value,
+                > = std::collections::BTreeMap::new();
+                let mut _unparsed = false;
+
+                while let Some((k, v)) = map.next_entry::<String, serde_json::Value>()? {
+                    match k.as_str() {
+                        "metric_name" => {
+                            if v.is_null() {
+                                continue;
+                            }
+                            metric_name =
+                                Some(serde_json::from_value(v).map_err(M::Error::custom)?);
+                        }
+                        &_ => {
+                            if let Ok(value) = serde_json::from_value(v.clone()) {
+                                additional_properties.insert(k, value);
+                            }
+                        }
+                    }
+                }
+
+                let content = MetricTagCardinalitiesMeta {
+                    metric_name,
+                    additional_properties,
+                    _unparsed,
+                };
+
+                Ok(content)
+            }
+        }
+
+        deserializer.deserialize_any(MetricTagCardinalitiesMetaVisitor)
+    }
+}