The 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.
openapi: 3.1.0
info:
title: Datadog Metrics 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/
externalDocs:
description: Datadog Metrics API Documentation
url: https://docs.datadoghq.com/api/latest/metrics/
servers:
- url: https://api.datadoghq.com
description: Datadog API Production Server
tags:
- name: Metric Metadata
description: View and manage metric metadata and active metrics
- name: Metric Tags
description: Manage metric tag configurations
- name: Metrics
description: Submit and query metric data points
security:
- apiKeyAuth: []
paths:
/api/v2/series:
post:
operationId: submitMetrics
summary: Datadog Submit Metrics
description: >-
Submits metrics data points to the Datadog platform. The body should
contain a series of metric submissions, each with a metric name, type,
data points (timestamp and value pairs), tags, and optional host and
resource information. Supports count, rate, gauge, and distribution
metric types. The maximum payload size is 512 KB (uncompressed). Each
metric series can contain up to 100 data points.
tags:
- Metrics
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/MetricPayload'
responses:
'202':
description: Payload accepted for processing
content:
application/json:
schema:
$ref: '#/components/schemas/IntakePayloadAccepted'
'400':
description: Bad request - invalid payload format or missing required fields
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'
'408':
description: Request timeout
content:
application/json:
schema:
$ref: '#/components/schemas/APIErrorResponse'
'413':
description: Payload too large - exceeds 512 KB limit
content:
application/json:
schema:
$ref: '#/components/schemas/APIErrorResponse'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/api/v2/query/timeseries:
post:
operationId: queryMetricsTimeseries
summary: Datadog Query Timeseries Data
description: >-
Queries timeseries metric data for the specified time range and metric
queries. Supports multiple metric queries in a single request. Returns
time series data including timestamps, values, and associated metadata.
The query uses Datadog's metrics query language supporting rollup,
aggregation, and arithmetic operations.
tags:
- Metrics
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/MetricTimeseriesQuery'
responses:
'200':
description: Successful response with timeseries data
content:
application/json:
schema:
$ref: '#/components/schemas/MetricTimeseriesResponse'
'400':
description: Bad request - invalid query syntax or 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'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/api/v2/query/scalar:
post:
operationId: queryMetricsScalar
summary: Datadog Query Scalar Data
description: >-
Queries scalar metric data for the specified time range and returns a
single aggregated value per query formula. Useful for computing summary
statistics such as averages, sums, or percentiles over a time window.
Supports multiple formulas and metric queries in a single request.
tags:
- Metrics
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/MetricScalarQuery'
responses:
'200':
description: Successful response with scalar query results
content:
application/json:
schema:
$ref: '#/components/schemas/MetricScalarResponse'
'400':
description: Bad request - invalid query syntax or 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'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/api/v1/metrics:
get:
operationId: listActiveMetrics
summary: Datadog List Active Metrics
description: >-
Returns the list of actively reporting metric names for a given hour.
Optionally filters by host and metric name prefix. Metrics are
considered active if they reported at least one data point within the
last 48 hours. Useful for metric discovery and auditing.
tags:
- Metric Metadata
parameters:
- name: from
in: query
required: true
description: POSIX timestamp (seconds) indicating the start of the time window to query active metrics
schema:
type: integer
format: int64
example: 42
- name: host
in: query
required: false
description: Filter metrics by the hostname that is actively reporting the metric
schema:
type: string
example: example_value
- name: tag_filter
in: query
required: false
description: Filter metrics by tag key or key:value pair (e.g., env:prod)
schema:
type: string
example: env:production
responses:
'200':
description: Successful response with list of active metrics
content:
application/json:
schema:
$ref: '#/components/schemas/MetricsListResponse'
'400':
description: Bad request - invalid or missing required 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'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/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:
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.
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:
MetricSeries:
type: object
description: A single metric series containing data points and associated metadata
required:
- metric
- points
properties:
metric:
type: string
description: The name of the metric to submit. Must not exceed 200 characters. Only ASCII alphanumerics, underscores, and periods are allowed.
example: example_value
type:
type: integer
description: The type of the metric (0=unspecified, 1=count, 2=rate, 3=gauge)
enum: [0, 1, 2, 3]
default: 3
points:
type: array
description: List of data points, each containing a timestamp (Unix epoch in seconds) and a value
items:
$ref: '#/components/schemas/MetricPoint'
tags:
type: array
description: List of tags associated with the metric in key:value format (e.g., env:prod)
items:
type: string
host:
type: string
description: The name of the host that produced the metric data
example: example_value
resources:
type: array
description: A list of resources associated with the metric, such as hosts or services
items:
$ref: '#/components/schemas/MetricResource'
interval:
type: integer
format: int64
description: If the type is rate or count, defines the corresponding interval in seconds
example: 42
unit:
type: string
description: The unit of the metric value (e.g., byte, second, request)
example: example_value
MetricPoint:
type: object
description: A single data point consisting of a Unix timestamp and a numeric value
required:
- timestamp
- value
properties:
timestamp:
type: integer
format: int64
description: The Unix timestamp in seconds when this data point was recorded
example: 42
value:
type: number
format: double
description: The numeric value of the metric at the given timestamp
example: 95.5
MetricResource:
type: object
description: A resource (such as a host or service) associated with a metric series
required:
- name
- type
properties:
name:
type: string
description: The name of the resource (e.g., hostname or service name)
example: Example Monitor
type:
type: string
description: The type of the resource (e.g., host, service, container)
example: metric alert
MetricPayload:
type: object
description: The payload containing one or more metric series to submit
required:
- series
properties:
series:
type: array
description: List of metric series to submit in this payload
items:
$ref: '#/components/schemas/MetricSeries'
IntakePayloadAccepted:
type: object
description: Response indicating the metric payload was accepted for processing
properties:
errors:
type: array
description: List of any non-fatal errors encountered when processing the payload
items:
type: string
MetricTimeseriesQuery:
type: object
description: Request body for querying timeseries metric data
required:
- data
properties:
data:
type: object
description: The query data object containing type and attributes
required:
- type
- attributes
properties:
type:
type: string
description: The type identifier for the query request
enum: [timeseries_request]
attributes:
type: object
description: The query attributes including formulas, queries, and time range
required:
- from
- to
- queries
properties:
from:
type: integer
format: int64
description: Unix timestamp in milliseconds for the start of the query time range
to:
type: integer
format: int64
description: Unix timestamp in milliseconds for the end of the query time range
interval:
type: integer
format: int64
description: The granularity (in milliseconds) for returned data points
queries:
type: array
description: List of metric queries to evaluate
items:
$ref: '#/components/schemas/MetricQueryDefinition'
formulas:
type: array
description: List of formula expressions combining the defined queries
items:
$ref: '#/components/schemas/QueryFormula'
MetricQueryDefinition:
type: object
description: A metric query definition referencing a Datadog metrics query expression
required:
- name
- data_source
- query
properties:
name:
type: string
description: A unique name used to reference this query in formula expressions
example: Example Monitor
data_source:
type: string
description: The data source for the query
enum: [metrics, cloud_cost]
example: metrics
query:
type: string
description: The Datadog metrics query string (e.g., avg:system.cpu.user{*} by {host})
example: avg:system.cpu.user{*}
QueryFormula:
type: object
description: A formula expression that combines one or more query results
required:
- formula
properties:
formula:
type: string
description: The formula expression using query names as variables (e.g., query1 + query2)
example: example_value
alias:
type: string
description: An optional alias for the formula result used in the response
example: example_value
limit:
type: object
description: Optional limit configuration for top/bottom N results
properties:
count:
type: integer
description: The number of results to return
order:
type: string
description: The sort order for limiting results
enum: [asc, desc]
MetricTimeseriesResponse:
type: object
description: Response containing timeseries metric data for the requested queries
properties:
data:
type: object
description: The response data object
properties:
type:
type: string
description: The type identifier for the response
id:
type: string
description: A unique identifier for this response
attributes:
type: object
description: The response attributes containing timeseries results
properties:
times:
type: array
description: Array of Unix timestamps in milliseconds for each data point
items:
type: integer
format: int64
series:
type: array
description: List of timeseries results, one per query formula
items:
$ref: '#/components/schemas/TimeseriesResult'
TimeseriesResult:
type: object
description: A single timeseries result for a query formula
properties:
query_index:
type: integer
description: Index of the query or formula that produced this result
example: 42
unit:
type: array
description: Unit information for the metric values in this series
items:
type: object
properties:
family:
type: string
description: The unit family (e.g., time, bytes, percent)
name:
type: string
description: The unit name (e.g., second, byte, percent)
group_tags:
type: array
description: The tag key:value pairs that identify this series within a group-by
items:
type: string
values:
type: array
description: The numeric values at each timestamp
items:
type: number
format: double
nullable: true
MetricScalarQuery:
type: object
description: Request body for querying scalar metric data
required:
- data
properties:
data:
type: object
description: The scalar query data object
required:
- type
- attributes
properties:
type:
type: string
description: The type identifier for the scalar query request
enum: [scalar_request]
attributes:
type: object
description: The scalar query attributes
required:
- from
- to
- queries
properties:
from:
type: integer
format: int64
description: Unix timestamp in milliseconds for the start of the query time range
to:
type: integer
format: int64
description: Unix timestamp in milliseconds for the end of the query time range
queries:
type: array
description: List of metric queries to evaluate as scalar values
items:
$ref: '#/components/schemas/MetricQueryDefinition'
formulas:
type: array
description: List of formula expressions combining the defined queries
items:
$ref: '#/components/schemas/QueryFormula'
MetricScalarResponse:
type: object
description: Response containing scalar metric values for the requested queries
properties:
data:
type: object
description: The scalar response data
properties:
type:
type: string
description: The type identifier for the response
id:
type: string
description: A unique identifier for this response
attributes:
type: object
description: The response attributes
properties:
columns:
type: array
description: List of scalar result columns, one per query formula
items:
$ref: '#/components/schemas/ScalarColumn'
ScalarColumn:
type: object
description: A single column of scalar results from a query formula
properties:
name:
type: string
description: The column name or formula alias
example: Example Monitor
values:
type: array
description: The scalar values for this column
items:
type: number
format: double
nullable: true
group:
type: array
description: The group-by tag values for each row in this column
items:
type: array
items:
type: string
MetricsListResponse:
type: object
description: Response containing the list of active metric names
properties:
from:
type: string
description: The start time of the active metrics query window as a Unix timestamp string
example: example_value
metrics:
type: array
description: The list of active metric names for the specified time window
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'
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
# --- truncated at 32 KB (32 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/datadog/refs/heads/main/openapi/datadog-metrics-openapi.yml