---
title: "Create a span-based metric"
method: POST
path: "/api/v2/apm/config/metrics"
tags: ["Spans Metrics"]
---

# Create a span-based metric

`POST /api/v2/apm/config/metrics`

## Request

- Base URL: `https://api.datadoghq.com`
- URL: `https://api.datadoghq.com/api/v2/apm/config/metrics`
- Auth: API key in header `DD-API-KEY` and API key in header `DD-APPLICATION-KEY`

Create a metric based on your ingested spans in your organization.
Returns the span-based metric object from the request body when the request is successful.

## Request body

- SpansMetricCreateRequest: The new span-based metric body.
  - `data` SpansMetricCreateData, required: The new span-based metric properties.
    - `attributes` SpansMetricCreateAttributes, required: The object describing the Datadog span-based metric to create.
      - `compute` SpansMetricCompute, required: The compute rule to compute the span-based metric.
        - `aggregation_type` 'count' | 'distribution', required: The type of aggregation to use.
        - `include_percentiles` boolean: Toggle to include or exclude percentile aggregations for distribution metrics. Only present when the `aggregation_type` is `distribution`.
        - `path` string: The path to the value the span-based metric will aggregate on (only used if the aggregation type is a "distribution").
      - `filter` SpansMetricFilter: The span-based metric filter. Spans matching this filter will be aggregated in this metric.
        - `query` string: The search query - following the span search syntax.
      - `group_by` SpansMetricGroupBy[]: The rules for the group by.
        - `path` string, required: The path to the value the span-based metric will be aggregated over.
        - `tag_name` string: Eventual name of the tag that gets created. By default, the path attribute is used as the tag name.
    - `id` string, required: The name of the span-based metric.
    - `type` 'spans_metrics', required: The type of resource. The value should always be spans_metrics.

## Response `200`

OK

- SpansMetricResponse: The span-based metric object.
  - `data` SpansMetricResponseData: The span-based metric properties.
    - `attributes` SpansMetricResponseAttributes: The object describing a Datadog span-based metric.
      - `compute` SpansMetricResponseCompute: The compute rule to compute the span-based metric.
        - `aggregation_type` 'count' | 'distribution': The type of aggregation to use.
        - `include_percentiles` boolean: Toggle to include or exclude percentile aggregations for distribution metrics. Only present when the `aggregation_type` is `distribution`.
        - `path` string: The path to the value the span-based metric will aggregate on (only used if the aggregation type is a "distribution").
      - `filter` SpansMetricResponseFilter: The span-based metric filter. Spans matching this filter will be aggregated in this metric.
        - `query` string: The search query - following the span search syntax.
      - `group_by` SpansMetricResponseGroupBy[]: The rules for the group by.
        - `path` string: The path to the value the span-based metric will be aggregated over.
        - `tag_name` string: Eventual name of the tag that gets created. By default, the path attribute is used as the tag name.
    - `id` string: The name of the span-based metric.
    - `type` 'spans_metrics': The type of resource. The value should always be spans_metrics.

## Other responses

- `400`: Bad Request
- `403`: Not Authorized
- `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/da68bf029e4c?raw)