Class MetricsApi

Create a derived metric for the org. The metric name is supplied as the resource id, and the definition sets the formula and the queries the formula is computed from. Requires the Manage Tags for Metrics permission.

Enable historical metrics ingestion (late data ingestion) for a metric. Idempotent: enabling an already-enabled metric returns 200 instead of 201. Not supported for distribution metrics, metrics with an existing tag configuration, or most standard (non-custom) metrics.

Create and define a list of queryable tag keys for an existing count/gauge/rate/distribution metric. Optionally, include percentile aggregations on any distribution metric. By setting exclude_tags_mode to true, the behavior is changed from an allow-list to a deny-list, and tags in the defined list are not queryable. Can only be used with application keys of users with the Manage Tags for Metrics permission.

Create a tag indexing rule for the org. rule_order is assigned server-side as max+1 among existing rules; use the reorder endpoint to change the evaluation order. Requires the Manage Tags for Metrics permission.

Exempt a metric from all tag indexing rules. The response includes the created exemption resource. Requires the Manage Tags for Metrics permission.

Delete a derived metric by name. Idempotent: returns 204 regardless of whether the derived metric existed. Requires the Manage Tags for Metrics permission.

Disable historical metrics ingestion for a metric. Idempotent: always returns 204, whether or not the configuration existed or the metric itself still exists, so that Terraform destroy succeeds for a metric removed out-of-band.

Deletes a metric's tag configuration. Can only be used with application keys from users with the Manage Tags for Metrics permission. Note: This operation is irreversible.

Soft-delete a tag indexing rule. Idempotent: returns 204 whether the rule existed or was already deleted. Remaining rules in the org are automatically re-sequenced to keep rule_order dense and 1-based. Requires the Manage Tags for Metrics permission.

Remove a metric's exemption from tag indexing rules. Idempotent: returns 204 whether or not an exemption existed. Any associated legacy tag configuration record is also removed. Requires the Manage Tags for Metrics permission.

Returns the estimated cardinality for a metric with a given tag, percentile and number of aggregations configuration using Metrics without Limits™.

To compare current volumes across many metrics, use GET /api/v2/metrics with include=metric_volumes instead of calling this endpoint for each metric.

Get the definition of a derived metric by name.

Get the historical metrics ingestion configuration for a metric. Existence of the resource means historical metrics ingestion is enabled; returns 404 when it is not enabled for the metric.

Returns the cardinality details of tags for a specific metric.

Get a single tag indexing rule by its UUID.

Returns why a metric is excluded from tag indexing rules. Returns 200 with kind=exemption when an explicit exemption exists, 200 with kind=legacy_tag_configuration when the metric has a legacy tag configuration acting as an implicit exclusion, or 404 when neither applies.

List tags and aggregations that are actively queried on dashboards, notebooks, monitors, the Metrics Explorer, and using the API for a given metric name.

To find which of many metrics are queried or not queried, use GET /api/v2/metrics with filter[queried] instead of calling this endpoint for each metric.

Returns dashboards, monitors, notebooks, and SLOs that a metric is stored in, if any. Updated every 24 hours.

Returns the tag configuration for the given metric name.

A metric may exist and submit data without having a tag configuration. A 404 Not Found response usually means that the metric has no tag configuration, but it is also returned when no metric with this name exists in your organization.

To list tag configurations for many metrics, use GET /api/v2/metrics with filter[configured]=true instead of calling this endpoint for each metric.

Get a list of actively reporting metrics for your organization, with optional volumes, query activity, and tag configuration filters. When you need volumes, query activity, or tag configuration status for many metrics, use this endpoint instead of calling per-metric endpoints (such as GET /api/v2/metrics/{metric_name}/volumes or GET /api/v2/metrics/{metric_name}/tags) in a loop, which is slower and quickly reaches rate limits. This endpoint does not return the tag keys or values that a metric was submitted with.

Always paginate: send page[size] (up to 10000; a few hundred to a few thousand is typical) and follow meta.pagination.next_cursor (or links.next) until it is null or missing. Without page[size] or page[cursor], the response is not paginated: it returns matching metrics in one response, with no pagination metadata, up to a limit of 250,000 metrics by default (some organizations have a different limit). Metrics beyond the limit are left out without any indication. Unpaginated requests in large organizations can also be slow or time out, and clients with response-size limits may fail or truncate the response. If a request with page[cursor] returns 410 Gone, the cursor has expired: restart from the first page (send page[size] without page[cursor]).

• Volumes: include=metric_volumes adds the indexed and ingested volume of each metric. The volume is a fixed one-hour value and is not affected by window[seconds]. Volumes are not returned inside data: each metric with volume data has a relationships.metric_volumes.data reference, and the volumes themselves are returned as metric_volumes resources in the top-level included array. To join them, match included[].id to the id of data[] items with type metrics; both are the metric name. manage_tags items in data repeat the same id, so skip them when joining. Metrics without volume data, such as standard (non-custom) metrics, have no metric_volumes reference or entry.
• Top metrics by volume: sort=-metric_volumes.indexed_volume together with include=metric_volumes and page[size] (for example, page[size]=20) returns the metrics with the highest indexed volume first. Sorting requires a paginated request.
• Volume for a family of metrics: filter[metrics.id]=http.request* with include=metric_volumes and page[size] returns volumes for every metric whose name starts with http.request (a value whose only * is at the end is case-sensitive). A value without * matches names that contain it, ignoring case.
• Unqueried metrics: filter[queried]=false with filter[queried][window][seconds] (for example, 2592000 for 30 days) and page[size] returns metrics that were not queried in that window.
• Metrics without a tag configuration: filter[configured]=false with page[size] returns custom metrics that have no Metrics without Limits™ tag configuration.
• Metric types: if filter[metric_type] is omitted, metrics of all types are returned.

Examples:

• Top 20 metrics by indexed volume: GET /api/v2/metrics?include=metric_volumes&sort=-metric_volumes.indexed_volume&page[size]=20
• Metrics not queried in the last 30 days, with their volumes: GET /api/v2/metrics?filter[queried]=false&filter[queried][window][seconds]=2592000&include=metric_volumes&page[size]=1000
• Metrics without a tag configuration: GET /api/v2/metrics?filter[configured]=false&page[size]=1000
• Volumes for metrics whose name starts with http.request: GET /api/v2/metrics?filter[metrics.id]=http.request*&include=metric_volumes&page[size]=1000

Query parameters use bracket notation (for example, filter[tags], filter[queried][window][seconds]). Pass them as standard URL query strings, URL-encoding the brackets if your client does not handle them. For example: GET /api/v2/metrics?filter[tags]=env:prod&window[seconds]=86400&page[size]=500.

Provide a paginated version of listTagConfigurations returning a generator with all the items.

Returns explicit exemptions and legacy tag configurations that exclude metrics from tag indexing rules. You can filter results by metric name prefix, whether an exemption is safe to remove, or the UUID of a matching tag indexing rule. You can sort results by metric name or by estimated change in indexed volume.

Provide a paginated version of listTagIndexingRuleExemptions returning a generator with all the items.

List tag indexing rules for an org, sorted by rule_order, with offset/limit pagination.

List the tag indexing rules that apply to a given metric, sorted by rule_order. Matching is performed server-side using each rule's metric_name_matches glob patterns.

View indexed and ingested tags for a given metric name. Results are filtered by the window[seconds] parameter, which defaults to 14400 (4 hours). This window only limits which tags are returned; it does not affect whether the metric is found.

A 404 Not Found response means that no metric with this exact name exists in your organization. Metric names must match exactly. Distribution metrics do not have suffixes such as .avg or .count, so use the base metric name.

For high-cardinality metrics, keep responses small with filter[include_tag_values]=false, page[limit], and filter[match].

View hourly average cardinality for the given metric name over the look back period. For Metric Name Pricing customers, view total point volume for the given metric name over the look back period.

To get the last hour's indexed and ingested volumes for many metrics, use GET /api/v2/metrics with include=metric_volumes instead of calling this endpoint for each metric. Use this endpoint when you need a longer look-back for a single metric.

Query scalar values (as seen on Query Value, Table, and Toplist widgets). Multiple data sources are supported with the ability to process the data using formulas and functions.

Query timeseries data across various data sources and process the data by applying formulas and functions. Datadog recommends using this endpoint over the v1 /api/v1/query endpoint for querying timeseries data.

Atomically re-sequence the tag indexing rules for an org to match the supplied list of rule UUIDs. The server assigns rule_order 1, 2, … matching each rule UUID by position in the list. The UUIDs of all active rules must be provided; omitting any active rule UUID returns a 400 error. Requires the Manage Tags for Metrics permission.

The metrics end-point allows you to post time-series data that can be graphed on Datadog’s dashboards. The maximum payload size is 500 kilobytes (512000 bytes). Compressed payloads must have a decompressed size of less than 5 megabytes (5242880 bytes).

If you’re submitting metrics directly to the Datadog API without using DogStatsD, expect:

• 64 bits for the timestamp
• 64 bits for the value
• 20 bytes for the metric names
• 50 bytes for the timeseries
• The full payload is approximately 100 bytes.

Host name is one of the resources in the Resources field.

Update the definition of an existing derived metric. The id in the request body must match the metric_name path parameter. Requires the Manage Tags for Metrics permission.

Update the tag configuration of a metric or percentile aggregations of a distribution metric or custom aggregations of a count, rate, or gauge metric. By setting exclude_tags_mode to true the behavior is changed from an allow-list to a deny-list, and tags in the defined list will not be queryable. Can only be used with application keys from users with the Manage Tags for Metrics permission. This endpoint requires a tag configuration to be created first.

Partially update a tag indexing rule. Fields omitted from the request body are left unchanged. Setting rule_order to a value already used by another rule returns 409; use the reorder endpoint for atomic re-sequencing. Requires the Manage Tags for Metrics permission.

Update the reason for an explicit tag indexing rule exemption. The exemption's created_at and created_by_handle values remain unchanged. Returns 404 when the metric has no explicit exemption or has only a legacy tag configuration. Requires the Manage Tags for Metrics permission.