Add Get Tag Cardinalities Endpoint Spec (#2409)

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:57.186"
+  "spec_repo_commit": "dc49df4",
+  "generated": "2025-07-18 13:58:29.146"
 }

.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.ts

@@ -0,0 +1,21 @@
+/**
+ * Get tag key cardinality details returns "Success" response
+ */
+
+import { client, v2 } from "@datadog/datadog-api-client";
+
+const configuration = client.createConfiguration();
+const apiInstance = new v2.MetricsApi(configuration);
+
+const params: v2.MetricsApiGetMetricTagCardinalityDetailsRequest = {
+  metricName: "metric_name",
+};
+
+apiInstance
+  .getMetricTagCardinalityDetails(params)
+  .then((data: v2.MetricTagCardinalitiesResponse) => {
+    console.log(
+      "API called successfully. Returned data: " + JSON.stringify(data)
+    );
+  })
+  .catch((error: any) => console.error(error));

features/support/scenarios_model_mapping.ts

@@ -5856,6 +5856,13 @@ export const ScenariosModelMappings: {[key: string]: {[key: string]: any}} = {
             },
         "operationResponseType": "MetricEstimateResponse",
     },
+    "v2.GetMetricTagCardinalityDetails": {
+        "metricName": {
+            "type": "string",
+            "format": "",
+            },
+        "operationResponseType": "MetricTagCardinalitiesResponse",
+    },
     "v2.DeleteTagConfiguration": {
         "metricName": {
             "type": "string",

features/v2/metrics.feature

@@ -152,6 +152,30 @@ Feature: Metrics
     Then the response status is 200 Success
     And the response "data[0].type" is equal to "manage_tags"
 
+  @generated @skip @team:DataDog/metrics-experience
+  Scenario: Get tag key cardinality details returns "Bad Request" response
+    Given a valid "appKeyAuth" key in the system
+    And new "GetMetricTagCardinalityDetails" request
+    And request contains "metric_name" parameter from "REPLACE.ME"
+    When the request is sent
+    Then the response status is 400 Bad Request
+
+  @generated @skip @team:DataDog/metrics-experience
+  Scenario: Get tag key cardinality details returns "Not Found" response
+    Given a valid "appKeyAuth" key in the system
+    And new "GetMetricTagCardinalityDetails" request
+    And request contains "metric_name" parameter from "REPLACE.ME"
+    When the request is sent
+    Then the response status is 404 Not Found
+
+  @generated @skip @team:DataDog/metrics-experience
+  Scenario: Get tag key cardinality details returns "Success" response
+    Given a valid "appKeyAuth" key in the system
+    And new "GetMetricTagCardinalityDetails" request
+    And request contains "metric_name" parameter from "REPLACE.ME"
+    When the request is sent
+    Then the response status is 200 Success
+
   @generated @skip @team:DataDog/metrics-experience
   Scenario: List active tags and aggregations returns "Bad Request" response
     Given a valid "appKeyAuth" key in the system

features/v2/undo.json

@@ -1864,6 +1864,12 @@
       "type": "safe"
     }
   },
+  "GetMetricTagCardinalityDetails": {
+    "tag": "Metrics",
+    "undo": {
+      "type": "safe"
+    }
+  },
   "DeleteTagConfiguration": {
     "tag": "Metrics",
     "undo": {

packages/datadog-api-client-v2/apis/MetricsApi.ts

@@ -29,6 +29,7 @@ import { MetricPayload } from "../models/MetricPayload";
 import { MetricsAndMetricTagConfigurations } from "../models/MetricsAndMetricTagConfigurations";
 import { MetricsAndMetricTagConfigurationsResponse } from "../models/MetricsAndMetricTagConfigurationsResponse";
 import { MetricSuggestedTagsAndAggregationsResponse } from "../models/MetricSuggestedTagsAndAggregationsResponse";
+import { MetricTagCardinalitiesResponse } from "../models/MetricTagCardinalitiesResponse";
 import { MetricTagConfigurationCreateRequest } from "../models/MetricTagConfigurationCreateRequest";
 import { MetricTagConfigurationMetricTypeCategory } from "../models/MetricTagConfigurationMetricTypeCategory";
 import { MetricTagConfigurationResponse } from "../models/MetricTagConfigurationResponse";
@@ -284,6 +285,40 @@ export class MetricsApiRequestFactory extends BaseAPIRequestFactory {
     return requestContext;
   }
 
+  public async getMetricTagCardinalityDetails(
+    metricName: string,
+    _options?: Configuration
+  ): Promise<RequestContext> {
+    const _config = _options || this.configuration;
+
+    // verify required parameter 'metricName' is not null or undefined
+    if (metricName === null || metricName === undefined) {
+      throw new RequiredError("metricName", "getMetricTagCardinalityDetails");
+    }
+
+    // Path Params
+    const localVarPath =
+      "/api/v2/metrics/{metric_name}/tag-cardinalities".replace(
+        "{metric_name}",
+        encodeURIComponent(String(metricName))
+      );
+
+    // Make Request Context
+    const requestContext = _config
+      .getServer("v2.MetricsApi.getMetricTagCardinalityDetails")
+      .makeRequestContext(localVarPath, HttpMethod.GET);
+    requestContext.setHeaderParam("Accept", "application/json");
+    requestContext.setHttpConfig(_config.httpConfig);
+
+    // Apply auth methods
+    applySecurityAuthentication(_config, requestContext, [
+      "apiKeyAuth",
+      "appKeyAuth",
+    ]);
+
+    return requestContext;
+  }
+
   public async listActiveMetricConfigurations(
     metricName: string,
     windowSeconds?: number,
@@ -1071,6 +1106,69 @@ export class MetricsApiResponseProcessor {
     );
   }
 
+  /**
+   * Unwraps the actual response sent by the server from the response context and deserializes the response content
+   * to the expected objects
+   *
+   * @params response Response returned by the server for a request to getMetricTagCardinalityDetails
+   * @throws ApiException if the response code was not in [200, 299]
+   */
+  public async getMetricTagCardinalityDetails(
+    response: ResponseContext
+  ): Promise<MetricTagCardinalitiesResponse> {
+    const contentType = ObjectSerializer.normalizeMediaType(
+      response.headers["content-type"]
+    );
+    if (response.httpStatusCode === 200) {
+      const body: MetricTagCardinalitiesResponse = ObjectSerializer.deserialize(
+        ObjectSerializer.parse(await response.body.text(), contentType),
+        "MetricTagCardinalitiesResponse"
+      ) as MetricTagCardinalitiesResponse;
+      return body;
+    }
+    if (
+      response.httpStatusCode === 400 ||
+      response.httpStatusCode === 403 ||
+      response.httpStatusCode === 404 ||
+      response.httpStatusCode === 429
+    ) {
+      const bodyText = ObjectSerializer.parse(
+        await response.body.text(),
+        contentType
+      );
+      let body: APIErrorResponse;
+      try {
+        body = ObjectSerializer.deserialize(
+          bodyText,
+          "APIErrorResponse"
+        ) as APIErrorResponse;
+      } catch (error) {
+        logger.debug(`Got error deserializing error: ${error}`);
+        throw new ApiException<APIErrorResponse>(
+          response.httpStatusCode,
+          bodyText
+        );
+      }
+      throw new ApiException<APIErrorResponse>(response.httpStatusCode, body);
+    }
+
+    // Work around for missing responses in specification, e.g. for petstore.yaml
+    if (response.httpStatusCode >= 200 && response.httpStatusCode <= 299) {
+      const body: MetricTagCardinalitiesResponse = ObjectSerializer.deserialize(
+        ObjectSerializer.parse(await response.body.text(), contentType),
+        "MetricTagCardinalitiesResponse",
+        ""
+      ) as MetricTagCardinalitiesResponse;
+      return body;
+    }
+
+    const body = (await response.body.text()) || "";
+    throw new ApiException<string>(
+      response.httpStatusCode,
+      'Unknown API Status Code!\nBody: "' + body + '"'
+    );
+  }
+
   /**
    * Unwraps the actual response sent by the server from the response context and deserializes the response content
    * to the expected objects
@@ -1772,6 +1870,14 @@ export interface MetricsApiEstimateMetricsOutputSeriesRequest {
   filterTimespanH?: number;
 }
 
+export interface MetricsApiGetMetricTagCardinalityDetailsRequest {
+  /**
+   * The name of the metric.
+   * @type string
+   */
+  metricName: string;
+}
+
 export interface MetricsApiListActiveMetricConfigurationsRequest {
   /**
    * The name of the metric.
@@ -2066,6 +2172,30 @@ export class MetricsApi {
     });
   }
 
+  /**
+   * Returns the cardinality details of tags for a specific metric.
+   * @param param The request object
+   */
+  public getMetricTagCardinalityDetails(
+    param: MetricsApiGetMetricTagCardinalityDetailsRequest,
+    options?: Configuration
+  ): Promise<MetricTagCardinalitiesResponse> {
+    const requestContextPromise =
+      this.requestFactory.getMetricTagCardinalityDetails(
+        param.metricName,
+        options
+      );
+    return requestContextPromise.then((requestContext) => {
+      return this.configuration.httpApi
+        .send(requestContext)
+        .then((responseContext) => {
+          return this.responseProcessor.getMetricTagCardinalityDetails(
+            responseContext
+          );
+        });
+    });
+  }
+
   /**
    * List tags and aggregations that are actively queried on dashboards, notebooks, monitors, the Metrics Explorer, and using the API for a given metric name.
    * @param param The request object

packages/datadog-api-client-v2/index.ts

@@ -385,6 +385,7 @@ export {
   MetricsApiDeleteBulkTagsMetricsConfigurationRequest,
   MetricsApiDeleteTagConfigurationRequest,
   MetricsApiEstimateMetricsOutputSeriesRequest,
+  MetricsApiGetMetricTagCardinalityDetailsRequest,
   MetricsApiListActiveMetricConfigurationsRequest,
   MetricsApiListMetricAssetsRequest,
   MetricsApiListTagConfigurationByNameRequest,
@@ -2164,6 +2165,10 @@ export { MetricsTimeseriesQuery } from "./models/MetricsTimeseriesQuery";
 export { MetricSuggestedTagsAndAggregations } from "./models/MetricSuggestedTagsAndAggregations";
 export { MetricSuggestedTagsAndAggregationsResponse } from "./models/MetricSuggestedTagsAndAggregationsResponse";
 export { MetricSuggestedTagsAttributes } from "./models/MetricSuggestedTagsAttributes";
+export { MetricTagCardinalitiesMeta } from "./models/MetricTagCardinalitiesMeta";
+export { MetricTagCardinalitiesResponse } from "./models/MetricTagCardinalitiesResponse";
+export { MetricTagCardinality } from "./models/MetricTagCardinality";
+export { MetricTagCardinalityAttributes } from "./models/MetricTagCardinalityAttributes";
 export { MetricTagConfiguration } from "./models/MetricTagConfiguration";
 export { MetricTagConfigurationAttributes } from "./models/MetricTagConfigurationAttributes";
 export { MetricTagConfigurationCreateAttributes } from "./models/MetricTagConfigurationCreateAttributes";