--- title: Create a derived metric description: Datadog, the leading service for cloud-scale monitoring. breadcrumbs: Docs > API Reference > Metrics --- > For the complete documentation index, see [llms.txt](https://docs.datadoghq.com/llms.txt). # Create a derived metric{% #create-a-derived-metric %} {% tab title="v2" %} | Datadog site | API endpoint | | ----------------- | ----------------------------------------------------------------- | | ap1.datadoghq.com | POST https://api.ap1.datadoghq.com/api/v2/metrics/derived-metrics | | ap2.datadoghq.com | POST https://api.ap2.datadoghq.com/api/v2/metrics/derived-metrics | | app.datadoghq.eu | POST https://api.datadoghq.eu/api/v2/metrics/derived-metrics | | app.ddog-gov.com | POST https://api.ddog-gov.com/api/v2/metrics/derived-metrics | | us2.ddog-gov.com | POST https://api.us2.ddog-gov.com/api/v2/metrics/derived-metrics | | uk1.datadoghq.com | POST https://api.uk1.datadoghq.com/api/v2/metrics/derived-metrics | | app.datadoghq.com | POST https://api.datadoghq.com/api/v2/metrics/derived-metrics | | us3.datadoghq.com | POST https://api.us3.datadoghq.com/api/v2/metrics/derived-metrics | | us5.datadoghq.com | POST https://api.us5.datadoghq.com/api/v2/metrics/derived-metrics | ### Overview 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. This endpoint requires the `metric_tags_write` permission. OAuth apps require the `metric_tags_write` authorization [scope](https://docs.datadoghq.com/api/latest/scopes.md#metrics) to access this endpoint. ### Request #### Body Data (required) {% tab title="Model" %} | Parent field | Field | Type | Description | | ------------ | ----------------------------- | -------- | --------------------------------------------------------------------------- | | | data [*required*] | object | Data object for creating or updating a derived metric. | | data | attributes [*required*] | object | Attributes of a derived metric. | | attributes | definition [*required*] | object | The definition of a derived metric as a formula over one or more queries. | | definition | formula [*required*] | string | The formula that combines the queries into the value of the derived metric. | | definition | queries [*required*] | [object] | The list of queries referenced by the formula. | | queries | data_source [*required*] | string | The data source that the query is run against. | | queries | name [*required*] | string | The name used to reference this query from the formula. | | queries | query [*required*] | string | The query string executed against the data source. | | data | id [*required*] | string | The derived metric name used as the resource ID. | | data | type [*required*] | enum | The derived metric resource type. Allowed enum values: `derived_metrics` | {% /tab %} {% tab title="Example" %} ```json { "data": { "attributes": { "definition": { "formula": "a", "queries": [ { "data_source": "metrics", "name": "a", "query": "avg:system.cpu.user{*}" } ] } }, "id": "test.derived.examplemetric", "type": "derived_metrics" } } ``` {% /tab %} ### Response {% tab title="201" %} Created {% tab title="Model" %} Response containing a single derived metric. | Parent field | Field | Type | Description | | ------------ | ----------------------------- | -------- | --------------------------------------------------------------------------- | | | data [*required*] | object | A derived metric resource object. | | data | attributes [*required*] | object | Attributes of a derived metric. | | attributes | definition [*required*] | object | The definition of a derived metric as a formula over one or more queries. | | definition | formula [*required*] | string | The formula that combines the queries into the value of the derived metric. | | definition | queries [*required*] | [object] | The list of queries referenced by the formula. | | queries | data_source [*required*] | string | The data source that the query is run against. | | queries | name [*required*] | string | The name used to reference this query from the formula. | | queries | query [*required*] | string | The query string executed against the data source. | | data | id [*required*] | string | The derived metric name used as the resource ID. | | data | type [*required*] | enum | The derived metric resource type. Allowed enum values: `derived_metrics` | {% /tab %} {% tab title="Example" %} ```json { "data": { "attributes": { "definition": { "formula": "a", "queries": [ { "data_source": "metrics", "name": "a", "query": "avg:system.cpu.user{*}" } ] } }, "id": "my.derived.metric", "type": "derived_metrics" } } ``` {% /tab %} {% /tab %} {% tab title="400" %} Bad Request {% tab title="Model" %} API error response. | Field | Type | Description | | ------------------------ | -------- | ----------------- | | errors [*required*] | [string] | A list of errors. | {% /tab %} {% tab title="Example" %} ```json { "errors": [ "Bad Request" ] } ``` {% /tab %} {% /tab %} {% tab title="403" %} Forbidden {% tab title="Model" %} API error response. | Field | Type | Description | | ------------------------ | -------- | ----------------- | | errors [*required*] | [string] | A list of errors. | {% /tab %} {% tab title="Example" %} ```json { "errors": [ "Bad Request" ] } ``` {% /tab %} {% /tab %} {% tab title="409" %} Conflict {% tab title="Model" %} API error response. | Field | Type | Description | | ------------------------ | -------- | ----------------- | | errors [*required*] | [string] | A list of errors. | {% /tab %} {% tab title="Example" %} ```json { "errors": [ "Bad Request" ] } ``` {% /tab %} {% /tab %} {% tab title="429" %} Too many requests {% tab title="Model" %} API error response. | Field | Type | Description | | ------------------------ | -------- | ----------------- | | errors [*required*] | [string] | A list of errors. | {% /tab %} {% tab title="Example" %} ```json { "errors": [ "Bad Request" ] } ``` {% /tab %} {% /tab %} ### Code Example ##### \## default # \# Use a Personal Access Token or Service Access Token export DD_BEARER_TOKEN="" \# Curl command curl -X POST "https://api.datadoghq.com/api/v2/metrics/derived-metrics" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer ${DD_BEARER_TOKEN}" \ -d @- << EOF { "data": { "attributes": { "definition": { "formula": "a", "queries": [ { "data_source": "metrics", "name": "a", "query": "avg:system.cpu.user{*}" } ] } }, "id": "my.derived.metric", "type": "derived_metrics" } } EOF {% /tab %}