Create a derived metric
POST
https://api.datadoghq.com/api/v2/metrics/derived-metricshttps://api.us3.datadoghq.com/api/v2/metrics/derived-metricshttps://api.us5.datadoghq.com/api/v2/metrics/derived-metricshttps://api.datadoghq.eu/api/v2/metrics/derived-metricshttps://api.ap1.datadoghq.com/api/v2/metrics/derived-metricshttps://api.ap2.datadoghq.com/api/v2/metrics/derived-metricshttps://api.uk1.datadoghq.com/api/v2/metrics/derived-metricshttps://api.ddog-gov.com/api/v2/metrics/derived-metricshttps://api.us2.ddog-gov.com/api/v2/metrics/derived-metricsOverview
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.
OAuth apps require the metric_tags_write authorization scope to access this endpoint.
Request
Body Data (required)
Field
Type
Description
data [required]object
Data object for creating or updating a derived metric.
attributes [required]object
Attributes of a derived metric.
definition [required]object
The definition of a derived metric as a formula over one or more queries.
formula [required]string
The formula that combines the queries into the value of the derived metric.
queries [required][object]
The list of queries referenced by the formula.
data_source [required]string
The data source that the query is run against.
name [required]string
The name used to reference this query from the formula.
query [required]string
The query string executed against the data source.
id [required]string
The derived metric name used as the resource ID.
type [required]enum
The derived metric resource type.
derived_metricsAllowed enum values:
derived_metrics{
"data": {
"attributes": {
"definition": {
"formula": "a",
"queries": [
{
"data_source": "metrics",
"name": "a",
"query": "avg:system.cpu.user{*}"
}
]
}
},
"id": "test.derived.examplemetric",
"type": "derived_metrics"
}
}Response
Created
Response containing a single derived metric.
Field
Type
Description
data [required]object
A derived metric resource object.
attributes [required]object
Attributes of a derived metric.
definition [required]object
The definition of a derived metric as a formula over one or more queries.
formula [required]string
The formula that combines the queries into the value of the derived metric.
queries [required][object]
The list of queries referenced by the formula.
data_source [required]string
The data source that the query is run against.
name [required]string
The name used to reference this query from the formula.
query [required]string
The query string executed against the data source.
id [required]string
The derived metric name used as the resource ID.
type [required]enum
The derived metric resource type.
derived_metricsAllowed enum values:
derived_metrics{
"data": {
"attributes": {
"definition": {
"formula": "a",
"queries": [
{
"data_source": "metrics",
"name": "a",
"query": "avg:system.cpu.user{*}"
}
]
}
},
"id": "my.derived.metric",
"type": "derived_metrics"
}
}Bad Request
API error response.
Field
Type
Description
errors [required][string]
A list of errors.
{
"errors": [
"Bad Request"
]
}Forbidden
API error response.
Field
Type
Description
errors [required][string]
A list of errors.
{
"errors": [
"Bad Request"
]
}Conflict
API error response.
Field
Type
Description
errors [required][string]
A list of errors.
{
"errors": [
"Bad Request"
]
}Too many requests
API error response.
Field
Type
Description
errors [required][string]
A list of errors.
{
"errors": [
"Bad Request"
]
}Code Example
Create a derived metric returns "Created" response
# Set your Datadog site and credentials
export DD_SITE="datadoghq.com"
# Use a Personal Access Token or Service Access Token
export DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>"
curl -X POST "https://api.${DD_SITE}/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": "test.derived.examplemetric",
"type": "derived_metrics"
}
}
EOF# Set your Datadog site and credentials
export DD_SITE="us3.datadoghq.com"
# Use a Personal Access Token or Service Access Token
export DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>"
curl -X POST "https://api.${DD_SITE}/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": "test.derived.examplemetric",
"type": "derived_metrics"
}
}
EOF# Set your Datadog site and credentials
export DD_SITE="us5.datadoghq.com"
# Use a Personal Access Token or Service Access Token
export DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>"
curl -X POST "https://api.${DD_SITE}/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": "test.derived.examplemetric",
"type": "derived_metrics"
}
}
EOF# Set your Datadog site and credentials
export DD_SITE="datadoghq.eu"
# Use a Personal Access Token or Service Access Token
export DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>"
curl -X POST "https://api.${DD_SITE}/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": "test.derived.examplemetric",
"type": "derived_metrics"
}
}
EOF# Set your Datadog site and credentials
export DD_SITE="ap1.datadoghq.com"
# Use a Personal Access Token or Service Access Token
export DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>"
curl -X POST "https://api.${DD_SITE}/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": "test.derived.examplemetric",
"type": "derived_metrics"
}
}
EOF# Set your Datadog site and credentials
export DD_SITE="ap2.datadoghq.com"
# Use a Personal Access Token or Service Access Token
export DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>"
curl -X POST "https://api.${DD_SITE}/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": "test.derived.examplemetric",
"type": "derived_metrics"
}
}
EOF# Set your Datadog site and credentials
export DD_SITE="uk1.datadoghq.com"
# Use a Personal Access Token or Service Access Token
export DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>"
curl -X POST "https://api.${DD_SITE}/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": "test.derived.examplemetric",
"type": "derived_metrics"
}
}
EOF# Set your Datadog site and credentials
export DD_SITE="ddog-gov.com"
# Use a Personal Access Token or Service Access Token
export DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>"
curl -X POST "https://api.${DD_SITE}/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": "test.derived.examplemetric",
"type": "derived_metrics"
}
}
EOF# Set your Datadog site and credentials
export DD_SITE="us2.ddog-gov.com"
# Use a Personal Access Token or Service Access Token
export DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>"
curl -X POST "https://api.${DD_SITE}/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": "test.derived.examplemetric",
"type": "derived_metrics"
}
}
EOF