Datadog Metric Tags API

openapi: 3.2.0
info:
  title: Datadog Metrics Metric Tags API
  description: The Datadog Metrics API allows you to post metrics data to be graphed on Datadog dashboards, query metrics from any time period as timeseries or scalar values, and modify tag configurations for metrics. It also supports viewing tags and volumes for metrics. Metrics data is stored as time series and can be queried programmatically for analysis and visualization.
  version: v2
  contact:
    name: Datadog Support
    url: https://www.datadoghq.com/support/
  termsOfService: https://www.datadoghq.com/legal/terms/
servers:
- url: https://api.datadoghq.com
  description: Datadog API Production Server
security:
- apiKeyAuth: []
tags:
- name: Metric Tags
  description: Manage metric tag configurations
paths:
  /api/v2/metrics/{metric_name}/tags:
    get:
      operationId: getMetricTagConfiguration
      summary: Datadog List Tags by Metric Name
      description: Returns the tag configuration for a specified metric including all configured tag keys, aggregation types, and exclude percentiles setting. Only available for custom metrics with tag configurations.
      tags:
      - Metric Tags
      parameters:
      - $ref: '#/components/parameters/metricNameParam'
      responses:
        '200':
          description: Successful response with metric tag configuration
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MetricTagConfigurationResponse'
        '401':
          description: Unauthorized - missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
        '403':
          description: Forbidden - insufficient permissions for this operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
        '404':
          description: Not found - metric does not exist or has no tag configuration
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: createMetricTagConfiguration
      summary: Datadog Create a Tag Configuration
      description: Creates a tag configuration for a specified custom metric. Allows specifying which tag keys to include, the metric type, whether to exclude percentile aggregations, and aggregation settings. Tag configurations reduce the number of custom metrics by limiting which tag combinations are stored.
      tags:
      - Metric Tags
      parameters:
      - $ref: '#/components/parameters/metricNameParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MetricTagConfigurationCreateRequest'
      responses:
        '201':
          description: Created - tag configuration created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MetricTagConfigurationResponse'
        '400':
          description: Bad request - invalid tag configuration parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
        '401':
          description: Unauthorized - missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
        '403':
          description: Forbidden - insufficient permissions for this operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
        '409':
          description: Conflict - tag configuration already exists for this metric
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    patch:
      operationId: updateMetricTagConfiguration
      summary: Datadog Update a Tag Configuration
      description: Updates the tag configuration for a specified custom metric. Supports partial updates using JSON merge patch semantics. Allows changing the set of tag keys, aggregation types, and exclude percentiles settings.
      tags:
      - Metric Tags
      parameters:
      - $ref: '#/components/parameters/metricNameParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MetricTagConfigurationUpdateRequest'
      responses:
        '200':
          description: Successful response with updated tag configuration
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MetricTagConfigurationResponse'
        '400':
          description: Bad request - invalid tag configuration parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
        '401':
          description: Unauthorized - missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
        '403':
          description: Forbidden - insufficient permissions for this operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
        '404':
          description: Not found - metric tag configuration does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      operationId: deleteMetricTagConfiguration
      summary: Datadog Delete a Tag Configuration
      description: Deletes the tag configuration for a specified custom metric. After deletion, all tag combinations for the metric will be stored again, which may increase custom metric usage. This action cannot be undone.
      tags:
      - Metric Tags
      parameters:
      - $ref: '#/components/parameters/metricNameParam'
      responses:
        '204':
          description: No content - tag configuration deleted successfully
        '401':
          description: Unauthorized - missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
        '403':
          description: Forbidden - insufficient permissions for this operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
        '404':
          description: Not found - metric tag configuration does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  parameters:
    metricNameParam:
      name: metric_name
      in: path
      required: true
      description: The name of the metric to manage tag configuration for (e.g., system.cpu.user)
      schema:
        type: string
  schemas:
    MetricTagConfigurationCreateRequest:
      type: object
      description: Request body for creating a new metric tag configuration
      required:
      - data
      properties:
        data:
          type: object
          description: The tag configuration data to create
          required:
          - type
          - id
          - attributes
          properties:
            type:
              type: string
              description: The resource type identifier
              enum:
              - manage_tags
            id:
              type: string
              description: The metric name to create the tag configuration for
            attributes:
              type: object
              description: The tag configuration attributes to set
              required:
              - metric_type
              - tags
              properties:
                metric_type:
                  type: string
                  description: The type of the metric
                  enum:
                  - gauge
                  - count
                  - rate
                  - distribution
                tags:
                  type: array
                  description: List of tag keys to include when storing metric data
                  items:
                    type: string
                include_percentiles:
                  type: boolean
                  description: Whether to include percentile aggregations (only for distribution metrics)
    MetricTagConfigurationUpdateRequest:
      type: object
      description: Request body for updating an existing metric tag configuration
      required:
      - data
      properties:
        data:
          type: object
          description: The tag configuration data to update
          required:
          - type
          - id
          - attributes
          properties:
            type:
              type: string
              description: The resource type identifier
              enum:
              - manage_tags
            id:
              type: string
              description: The metric name of the tag configuration to update
            attributes:
              type: object
              description: The tag configuration attributes to update
              properties:
                tags:
                  type: array
                  description: Updated list of tag keys to include when storing metric data
                  items:
                    type: string
                include_percentiles:
                  type: boolean
                  description: Whether to include percentile aggregations (only for distribution metrics)
    APIErrorResponse:
      type: object
      description: Standard API error response returned for failed requests
      required:
      - errors
      properties:
        errors:
          type: array
          description: List of error messages describing the failure
          items:
            type: string
    MetricTagConfiguration:
      type: object
      description: The tag configuration for a custom metric
      properties:
        id:
          type: string
          description: The metric name that this tag configuration applies to
          example: abc-123-def
        type:
          type: string
          description: The resource type identifier
          enum:
          - manage_tags
          example: manage_tags
        attributes:
          type: object
          description: The tag configuration attributes
          properties:
            tags:
              type: array
              description: List of tag keys to include when storing this metric
              items:
                type: string
            metric_type:
              type: string
              description: The type of metric this configuration applies to
              enum:
              - gauge
              - count
              - rate
              - distribution
            include_percentiles:
              type: boolean
              description: Whether to include percentile aggregations for distribution metrics
            aggregations:
              type: array
              description: List of aggregation types to compute for this metric
              items:
                type: object
                properties:
                  space:
                    type: string
                    description: The spatial aggregation type
                    enum:
                    - avg
                    - max
                    - min
                    - sum
                  time:
                    type: string
                    description: The temporal aggregation type
                    enum:
                    - avg
                    - count
                    - max
                    - min
                    - sum
            created_at:
              type: string
              format: date-time
              description: ISO 8601 timestamp when this tag configuration was created
            modified_at:
              type: string
              format: date-time
              description: ISO 8601 timestamp when this tag configuration was last modified
    MetricTagConfigurationResponse:
      type: object
      description: Response wrapper for a metric tag configuration
      properties:
        data:
          $ref: '#/components/schemas/MetricTagConfiguration'
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: DD-API-KEY
      description: Datadog API key for authenticating requests. Obtain from the Datadog organization settings under API Keys.
externalDocs:
  description: Datadog Metrics API Documentation
  url: https://docs.datadoghq.com/api/latest/metrics/