---
title: "Create a derived metric"
method: POST
path: "/api/v2/metrics/derived-metrics"
tags: ["Metrics"]
---

# Create a derived metric

`POST /api/v2/metrics/derived-metrics`

## Request

- Base URL: `https://api.datadoghq.com`
- URL: `https://api.datadoghq.com/api/v2/metrics/derived-metrics`
- Auth: one of:
  - API key in header `DD-API-KEY` and API key in header `DD-APPLICATION-KEY`
  - OAuth 2
    - Authorization code: `/oauth2/v1/authorize`
    - Token URL: `/oauth2/v1/token` scopes: `metric_tags_write`
- TypeScript: <https://skmtc.dev/datadog/apis/datadog-api-v2-collection/docs/api/v2/metrics/derived-metrics/post.ts> (a function with typed inputs; its response is checked against the schema)

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.

## Request body

- DerivedMetricCreateRequest: Request body for creating or updating a derived metric.
  - `data` DerivedMetricCreateData, required: Data object for creating or updating a derived metric.
    - `attributes` DerivedMetricAttributes, required: Attributes of a derived metric.
      - `definition` DerivedMetricDefinition, required: The definition of a derived metric as a formula over one or more queries.
        - `formula` string, required: The formula that combines the queries into the value of the derived metric.
        - `queries` DerivedMetricQuery[], required: The list of queries referenced by the formula.
          - `data_source` string, required: The data source that the query is run against.
          - `name` string, required: The name used to reference this query from the formula.
          - `query` string, required: The query string executed against the data source.
    - `id` string, required: The derived metric name used as the resource ID.
    - `type` 'derived_metrics', required: The derived metric resource type.

## Response `201`

Created

- DerivedMetricResponse: Response containing a single derived metric.
  - `data` DerivedMetricData, required: A derived metric resource object.
    - `attributes` DerivedMetricAttributes, required: Attributes of a derived metric.
      - `definition` DerivedMetricDefinition, required: The definition of a derived metric as a formula over one or more queries.
        - `formula` string, required: The formula that combines the queries into the value of the derived metric.
        - `queries` DerivedMetricQuery[], required: The list of queries referenced by the formula.
          - `data_source` string, required: The data source that the query is run against.
          - `name` string, required: The name used to reference this query from the formula.
          - `query` string, required: The query string executed against the data source.
    - `id` string, required: The derived metric name used as the resource ID.
    - `type` 'derived_metrics', required: The derived metric resource type.

## Other responses

- `400`: Bad Request
- `403`: Forbidden
- `409`: Conflict
- `429`: Too many requests

---

[API](https://skmtc.dev/datadog/apis/datadog-api-v2-collection.md) - [All operations](https://skmtc.dev/datadog/apis/datadog-api-v2-collection/llms.txt) - [OpenAPI document](https://skmtc.dev/datadog/apis/datadog-api-v2-collection/revisions/3f70db624329?raw)