Add Get Tag Cardinalities Endpoint Spec (#2487)

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

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

@@ -0,0 +1,5 @@
+# Get tag key cardinality details returns "Success" response
+
+require "datadog_api_client"
+api_instance = DatadogAPIClient::V2::MetricsAPI.new
+p api_instance.get_metric_tag_cardinality_details("metric_name")

features/scenarios_model_mapping.rb

@@ -2055,6 +2055,9 @@
             "filter_pct" => "Boolean",
             "filter_timespan_h" => "Integer",
     },
+    "v2.GetMetricTagCardinalityDetails" => {
+            "metric_name" => "String",
+    },
     "v2.DeleteTagConfiguration" => {
             "metric_name" => "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": {

lib/datadog_api_client/inflector.rb

@@ -2340,6 +2340,10 @@ def overrides
           "v2.metric_suggested_tags_and_aggregations" => "MetricSuggestedTagsAndAggregations",
           "v2.metric_suggested_tags_and_aggregations_response" => "MetricSuggestedTagsAndAggregationsResponse",
           "v2.metric_suggested_tags_attributes" => "MetricSuggestedTagsAttributes",
+          "v2.metric_tag_cardinalities_meta" => "MetricTagCardinalitiesMeta",
+          "v2.metric_tag_cardinalities_response" => "MetricTagCardinalitiesResponse",
+          "v2.metric_tag_cardinality" => "MetricTagCardinality",
+          "v2.metric_tag_cardinality_attributes" => "MetricTagCardinalityAttributes",
           "v2.metric_tag_configuration" => "MetricTagConfiguration",
           "v2.metric_tag_configuration_attributes" => "MetricTagConfigurationAttributes",
           "v2.metric_tag_configuration_create_attributes" => "MetricTagConfigurationCreateAttributes",

lib/datadog_api_client/v2/api/metrics_api.rb

@@ -395,6 +395,71 @@ def estimate_metrics_output_series_with_http_info(metric_name, opts = {})
       return data, status_code, headers
     end
 
+    # Get tag key cardinality details.
+    #
+    # @see #get_metric_tag_cardinality_details_with_http_info
+    def get_metric_tag_cardinality_details(metric_name, opts = {})
+      data, _status_code, _headers = get_metric_tag_cardinality_details_with_http_info(metric_name, opts)
+      data
+    end
+
+    # Get tag key cardinality details.
+    #
+    # Returns the cardinality details of tags for a specific metric.
+    #
+    # @param metric_name [String] The name of the metric.
+    # @param opts [Hash] the optional parameters
+    # @return [Array<(MetricTagCardinalitiesResponse, Integer, Hash)>] MetricTagCardinalitiesResponse data, response status code and response headers
+    def get_metric_tag_cardinality_details_with_http_info(metric_name, opts = {})
+
+      if @api_client.config.debugging
+        @api_client.config.logger.debug 'Calling API: MetricsAPI.get_metric_tag_cardinality_details ...'
+      end
+      # verify the required parameter 'metric_name' is set
+      if @api_client.config.client_side_validation && metric_name.nil?
+        fail ArgumentError, "Missing the required parameter 'metric_name' when calling MetricsAPI.get_metric_tag_cardinality_details"
+      end
+      # resource path
+      local_var_path = '/api/v2/metrics/{metric_name}/tag-cardinalities'.sub('{metric_name}', CGI.escape(metric_name.to_s).gsub('%2F', '/'))
+
+      # query parameters
+      query_params = opts[:query_params] || {}
+
+      # header parameters
+      header_params = opts[:header_params] || {}
+      # HTTP header 'Accept' (if needed)
+      header_params['Accept'] = @api_client.select_header_accept(['application/json'])
+
+      # form parameters
+      form_params = opts[:form_params] || {}
+
+      # http body (model)
+      post_body = opts[:debug_body]
+
+      # return_type
+      return_type = opts[:debug_return_type] || 'MetricTagCardinalitiesResponse'
+
+      # auth_names
+      auth_names = opts[:debug_auth_names] || [:apiKeyAuth, :appKeyAuth]
+
+      new_options = opts.merge(
+        :operation => :get_metric_tag_cardinality_details,
+        :header_params => header_params,
+        :query_params => query_params,
+        :form_params => form_params,
+        :body => post_body,
+        :auth_names => auth_names,
+        :return_type => return_type,
+        :api_version => "V2"
+      )
+
+      data, status_code, headers = @api_client.call_api(Net::HTTP::Get, local_var_path, new_options)
+      if @api_client.config.debugging
+        @api_client.config.logger.debug "API called: MetricsAPI#get_metric_tag_cardinality_details\nData: #{data.inspect}\nStatus code: #{status_code}\nHeaders: #{headers}"
+      end
+      return data, status_code, headers
+    end
+
     # List active tags and aggregations.
     #
     # @see #list_active_metric_configurations_with_http_info

lib/datadog_api_client/v2/models/metric_tag_cardinalities_meta.rb

@@ -0,0 +1,107 @@
+=begin
+#Datadog API V2 Collection
+
+#Collection of all Datadog Public endpoints.
+
+The version of the OpenAPI document: 1.0
+Contact: [email protected]
+Generated by: https://github.com/DataDog/datadog-api-client-ruby/tree/master/.generator
+
+ 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 2020-Present Datadog, Inc.
+
+=end
+
+require 'date'
+require 'time'
+
+module DatadogAPIClient::V2
+  # Response metadata object.
+  class MetricTagCardinalitiesMeta
+    include BaseGenericModel
+
+    # The name of metric for which the tag cardinalities are returned.
+    # This matches the metric name provided in the request.
+    #
+    attr_accessor :metric_name
+
+    attr_accessor :additional_properties
+
+    # Attribute mapping from ruby-style variable name to JSON key.
+    # @!visibility private
+    def self.attribute_map
+      {
+        :'metric_name' => :'metric_name'
+      }
+    end
+
+    # Attribute type mapping.
+    # @!visibility private
+    def self.openapi_types
+      {
+        :'metric_name' => :'String'
+      }
+    end
+
+    # Initializes the object
+    # @param attributes [Hash] Model attributes in the form of hash
+    # @!visibility private
+    def initialize(attributes = {})
+      if (!attributes.is_a?(Hash))
+        fail ArgumentError, "The input argument (attributes) must be a hash in `DatadogAPIClient::V2::MetricTagCardinalitiesMeta` initialize method"
+      end
+
+      self.additional_properties = {}
+      # check to see if the attribute exists and convert string to symbol for hash key
+      attributes = attributes.each_with_object({}) { |(k, v), h|
+        if (!self.class.attribute_map.key?(k.to_sym))
+          self.additional_properties[k.to_sym] = v
+        else
+          h[k.to_sym] = v
+        end
+      }
+
+      if attributes.key?(:'metric_name')
+        self.metric_name = attributes[:'metric_name']
+      end
+    end
+
+    # Returns the object in the form of hash, with additionalProperties support.
+    # @return [Hash] Returns the object in the form of hash
+    # @!visibility private
+    def to_hash
+      hash = {}
+      self.class.attribute_map.each_pair do |attr, param|
+        value = self.send(attr)
+        if value.nil?
+          is_nullable = self.class.openapi_nullable.include?(attr)
+          next if !is_nullable || (is_nullable && !instance_variable_defined?(:"@#{attr}"))
+        end
+
+        hash[param] = _to_hash(value)
+      end
+      self.additional_properties.each_pair do |attr, value|
+        hash[attr] = value
+      end
+      hash
+    end
+
+    # Checks equality by comparing each attribute.
+    # @param o [Object] Object to be compared
+    # @!visibility private
+    def ==(o)
+      return true if self.equal?(o)
+      self.class == o.class &&
+          metric_name == o.metric_name &&
+          additional_properties == o.additional_properties
+    end
+
+    # Calculates hash code according to all attributes.
+    # @return [Integer] Hash code
+    # @!visibility private
+    def hash
+      [metric_name, additional_properties].hash
+    end
+  end
+end