Add Get Tag Cardinalities Endpoint Spec (#2548)

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:22:42.241"
+  "spec_repo_commit": "dc49df4",
+  "generated": "2025-07-18 13:57:17.436"
 }

.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

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": {

private/bdd_runner/src/support/scenarios_model_mapping.ts

@@ -5866,6 +5866,13 @@ export const ScenariosModelMappings: { [key: string]: OperationMapping } = {
     },
     operationResponseType: "MetricEstimateResponse",
   },
+  "MetricsApi.V2.GetMetricTagCardinalityDetails": {
+    metricName: {
+      type: "string",
+      format: "",
+    },
+    operationResponseType: "MetricTagCardinalitiesResponse",
+  },
   "MetricsApi.V2.ListTagConfigurationByName": {
     metricName: {
       type: "string",

services/metrics/src/v2/MetricsApi.ts

@@ -35,6 +35,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";
@@ -344,6 +345,51 @@ 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 { server, overrides } = _config.getServerAndOverrides(
+      "MetricsApi.v2.getMetricTagCardinalityDetails",
+      MetricsApi.operationServers,
+    );
+    const requestContext = server.makeRequestContext(
+      localVarPath,
+      HttpMethod.GET,
+      overrides,
+    );
+    requestContext.setHeaderParam("Accept", "application/json");
+    requestContext.setHttpConfig(_config.httpConfig);
+
+    // Set User-Agent
+    if (this.userAgent) {
+      requestContext.setHeaderParam("User-Agent", this.userAgent);
+    }
+
+    // Apply auth methods
+    applySecurityAuthentication(_config, requestContext, [
+      "apiKeyAuth",
+      "appKeyAuth",
+    ]);
+
+    return requestContext;
+  }
+
   public async listActiveMetricConfigurations(
     metricName: string,
     windowSeconds?: number,
@@ -1213,6 +1259,67 @@ 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 = normalizeMediaType(response.headers["content-type"]);
+    if (response.httpStatusCode === 200) {
+      const body: MetricTagCardinalitiesResponse = deserialize(
+        parse(await response.body.text(), contentType),
+        TypingInfo,
+        "MetricTagCardinalitiesResponse",
+      ) as MetricTagCardinalitiesResponse;
+      return body;
+    }
+    if (
+      response.httpStatusCode === 400 ||
+      response.httpStatusCode === 403 ||
+      response.httpStatusCode === 404 ||
+      response.httpStatusCode === 429
+    ) {
+      const bodyText = parse(await response.body.text(), contentType);
+      let body: APIErrorResponse;
+      try {
+        body = deserialize(
+          bodyText,
+          TypingInfo,
+          "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 = deserialize(
+        parse(await response.body.text(), contentType),
+        TypingInfo,
+        "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
@@ -1890,6 +1997,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.
@@ -2186,6 +2301,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

services/metrics/src/v2/index.ts

@@ -4,6 +4,7 @@ export {
   MetricsApiDeleteBulkTagsMetricsConfigurationRequest,
   MetricsApiDeleteTagConfigurationRequest,
   MetricsApiEstimateMetricsOutputSeriesRequest,
+  MetricsApiGetMetricTagCardinalityDetailsRequest,
   MetricsApiListActiveMetricConfigurationsRequest,
   MetricsApiListMetricAssetsRequest,
   MetricsApiListTagConfigurationByNameRequest,
@@ -103,6 +104,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";