Datadog APM Spans Metrics API

openapi: 3.0.0
info:
  title: Datadog APM Spans Metrics API
  description: The Spans Metrics operations of the Datadog API, extracted verbatim from the OpenAPI definition
    Datadog publishes for its own API clients.
  version: '1.0'
  contact:
    email: support@datadoghq.com
    name: Datadog Support
    url: https://www.datadoghq.com/support/
  x-source: https://raw.githubusercontent.com/DataDog/datadog-api-client-go/master/.generator/schemas/v2/openapi.yaml
  x-extracted: '2026-09-05'
  x-extraction-note: Path items, components and security schemes copied VERBATIM from the Datadog-published
    OpenAPI at x-source; only the APM-relevant subset of paths is retained. No content was authored by
    API Evangelist.
servers:
- url: https://{subdomain}.{site}
  variables:
    site:
      default: datadoghq.com
      description: The regional site for Datadog customers.
      enum:
      - datadoghq.com
      - us3.datadoghq.com
      - us5.datadoghq.com
      - ap1.datadoghq.com
      - ap2.datadoghq.com
      - uk1.datadoghq.com
      - datadoghq.eu
      - ddog-gov.com
      - us2.ddog-gov.com
      - uk1.datadoghq.com
    subdomain:
      default: api
      description: The subdomain where the API is deployed.
- url: '{protocol}://{name}'
  variables:
    name:
      default: api.datadoghq.com
      description: Full site DNS name.
    protocol:
      default: https
      description: The protocol for accessing the API.
- url: https://{subdomain}.{site}
  variables:
    site:
      default: datadoghq.com
      description: Any Datadog deployment.
    subdomain:
      default: api
      description: The subdomain where the API is deployed.
security:
- apiKeyAuth: []
  appKeyAuth: []
tags:
- description: Manage configuration of [span-based metrics](https://app.datadoghq.com/apm/traces/generate-metrics)
    for your organization. See [Generate Metrics from Spans](https://docs.datadoghq.com/tracing/trace_pipeline/generate_metrics/)
    for more information.
  externalDocs:
    description: Find out more at
    url: https://docs.datadoghq.com/tracing/metrics/metrics_namespace/
  name: Spans Metrics
paths:
  /api/v2/apm/config/metrics:
    get:
      description: Get the list of configured span-based metrics with their definitions.
      operationId: ListSpansMetrics
      responses:
        '200':
          content:
            application/json:
              examples:
                default:
                  value:
                    data:
                    - attributes:
                        compute:
                          aggregation_type: distribution
                          include_percentiles: false
                          path: '@duration'
                        filter:
                          query: '@http.status_code:200 service:my-service'
                        group_by:
                        - path: resource_name
                          tag_name: resource_name
                      id: my.metric
                      type: spans_metrics
              schema:
                $ref: '#/components/schemas/SpansMetricsResponse'
          description: OK
        '403':
          $ref: '#/components/responses/NotAuthorizedResponse'
        '429':
          $ref: '#/components/responses/TooManyRequestsResponse'
      summary: Get all span-based metrics
      tags:
      - Spans Metrics
      x-permission:
        operator: OR
        permissions:
        - apm_read
    post:
      description: '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.'
      operationId: CreateSpansMetric
      requestBody:
        content:
          application/json:
            examples:
              default:
                value:
                  data:
                    attributes:
                      compute:
                        aggregation_type: distribution
                        include_percentiles: false
                        path: '@duration'
                      filter:
                        query: '@http.status_code:200 service:my-service'
                      group_by:
                      - path: resource_name
                        tag_name: resource_name
                    id: my.metric
                    type: spans_metrics
            schema:
              $ref: '#/components/schemas/SpansMetricCreateRequest'
        description: The definition of the new span-based metric.
        required: true
      responses:
        '200':
          content:
            application/json:
              examples:
                default:
                  value:
                    data:
                      attributes:
                        compute:
                          aggregation_type: distribution
                          include_percentiles: false
                          path: '@duration'
                        filter:
                          query: '@http.status_code:200 service:my-service'
                        group_by:
                        - path: resource_name
                          tag_name: resource_name
                      id: my.metric
                      type: spans_metrics
              schema:
                $ref: '#/components/schemas/SpansMetricResponse'
          description: OK
        '400':
          $ref: '#/components/responses/BadRequestResponse'
        '403':
          $ref: '#/components/responses/NotAuthorizedResponse'
        '409':
          $ref: '#/components/responses/ConflictResponse'
        '429':
          $ref: '#/components/responses/TooManyRequestsResponse'
      summary: Create a span-based metric
      tags:
      - Spans Metrics
      x-codegen-request-body-name: body
      x-permission:
        operator: OR
        permissions:
        - apm_generate_metrics
  /api/v2/apm/config/metrics/{metric_id}:
    delete:
      description: Delete a specific span-based metric from your organization.
      operationId: DeleteSpansMetric
      parameters:
      - $ref: '#/components/parameters/SpansMetricIDParameter'
      responses:
        '204':
          description: OK
        '403':
          $ref: '#/components/responses/NotAuthorizedResponse'
        '404':
          $ref: '#/components/responses/NotFoundResponse'
        '429':
          $ref: '#/components/responses/TooManyRequestsResponse'
      summary: Delete a span-based metric
      tags:
      - Spans Metrics
      x-permission:
        operator: OR
        permissions:
        - apm_generate_metrics
    get:
      description: Get a specific span-based metric from your organization.
      operationId: GetSpansMetric
      parameters:
      - $ref: '#/components/parameters/SpansMetricIDParameter'
      responses:
        '200':
          content:
            application/json:
              examples:
                default:
                  value:
                    data:
                      attributes:
                        compute:
                          aggregation_type: distribution
                          include_percentiles: false
                          path: '@duration'
                        filter:
                          query: '@http.status_code:200 service:my-service'
                        group_by:
                        - path: resource_name
                          tag_name: resource_name
                      id: my.metric
                      type: spans_metrics
              schema:
                $ref: '#/components/schemas/SpansMetricResponse'
          description: OK
        '403':
          $ref: '#/components/responses/NotAuthorizedResponse'
        '404':
          $ref: '#/components/responses/NotFoundResponse'
        '429':
          $ref: '#/components/responses/TooManyRequestsResponse'
      summary: Get a span-based metric
      tags:
      - Spans Metrics
      x-permission:
        operator: OR
        permissions:
        - apm_read
    patch:
      description: 'Update a specific span-based metric from your organization.

        Returns the span-based metric object from the request body when the request is successful.'
      operationId: UpdateSpansMetric
      parameters:
      - $ref: '#/components/parameters/SpansMetricIDParameter'
      requestBody:
        content:
          application/json:
            examples:
              default:
                value:
                  data:
                    attributes:
                      compute:
                        include_percentiles: false
                      filter:
                        query: '@http.status_code:200 service:my-service'
                      group_by:
                      - path: resource_name
                        tag_name: resource_name
                    type: spans_metrics
            schema:
              $ref: '#/components/schemas/SpansMetricUpdateRequest'
        description: New definition of the span-based metric.
        required: true
      responses:
        '200':
          content:
            application/json:
              examples:
                default:
                  value:
                    data:
                      attributes:
                        compute:
                          aggregation_type: distribution
                          include_percentiles: false
                          path: '@duration'
                        filter:
                          query: '@http.status_code:200 service:my-service'
                        group_by:
                        - path: resource_name
                          tag_name: resource_name
                      id: my.metric
                      type: spans_metrics
              schema:
                $ref: '#/components/schemas/SpansMetricResponse'
          description: OK
        '400':
          $ref: '#/components/responses/BadRequestResponse'
        '403':
          $ref: '#/components/responses/NotAuthorizedResponse'
        '404':
          $ref: '#/components/responses/NotFoundResponse'
        '429':
          $ref: '#/components/responses/TooManyRequestsResponse'
      summary: Update a span-based metric
      tags:
      - Spans Metrics
      x-codegen-request-body-name: body
      x-permission:
        operator: OR
        permissions:
        - apm_generate_metrics
components:
  schemas:
    SpansMetricsResponse:
      description: All the available span-based metric objects.
      properties:
        data:
          description: A list of span-based metric objects.
          items:
            $ref: '#/components/schemas/SpansMetricResponseData'
          type: array
      type: object
    SpansMetricCreateRequest:
      description: The new span-based metric body.
      properties:
        data:
          $ref: '#/components/schemas/SpansMetricCreateData'
      required:
      - data
      type: object
    APIErrorResponse:
      description: API error response.
      properties:
        errors:
          description: A list of errors.
          example:
          - Bad Request
          items:
            description: A list of items.
            example: Bad Request
            type: string
          type: array
      required:
      - errors
      type: object
    SpansMetricUpdateRequest:
      description: The new span-based metric body.
      properties:
        data:
          $ref: '#/components/schemas/SpansMetricUpdateData'
      required:
      - data
      type: object
    SpansMetricCreateData:
      description: The new span-based metric properties.
      properties:
        attributes:
          $ref: '#/components/schemas/SpansMetricCreateAttributes'
        id:
          $ref: '#/components/schemas/SpansMetricID'
        type:
          $ref: '#/components/schemas/SpansMetricType'
      required:
      - id
      - type
      - attributes
      type: object
    SpansMetricResponse:
      description: The span-based metric object.
      properties:
        data:
          $ref: '#/components/schemas/SpansMetricResponseData'
      type: object
    SpansMetricResponseData:
      description: The span-based metric properties.
      properties:
        attributes:
          $ref: '#/components/schemas/SpansMetricResponseAttributes'
        id:
          $ref: '#/components/schemas/SpansMetricID'
        type:
          $ref: '#/components/schemas/SpansMetricType'
      type: object
    SpansMetricResponseAttributes:
      description: The object describing a Datadog span-based metric.
      properties:
        compute:
          $ref: '#/components/schemas/SpansMetricResponseCompute'
        filter:
          $ref: '#/components/schemas/SpansMetricResponseFilter'
        group_by:
          description: The rules for the group by.
          items:
            $ref: '#/components/schemas/SpansMetricResponseGroupBy'
          type: array
      type: object
    SpansMetricResponseFilter:
      description: The span-based metric filter. Spans matching this filter will be aggregated in this
        metric.
      properties:
        query:
          description: The search query - following the span search syntax.
          example: '@http.status_code:200 service:my-service'
          type: string
      type: object
    SpansMetricID:
      description: The name of the span-based metric.
      example: my.metric
      type: string
    SpansMetricUpdateData:
      description: The new span-based metric properties.
      properties:
        attributes:
          $ref: '#/components/schemas/SpansMetricUpdateAttributes'
        type:
          $ref: '#/components/schemas/SpansMetricType'
      required:
      - type
      - attributes
      type: object
    SpansMetricResponseGroupBy:
      description: A group by rule.
      properties:
        path:
          description: The path to the value the span-based metric will be aggregated over.
          example: resource_name
          type: string
        tag_name:
          description: Eventual name of the tag that gets created. By default, the path attribute is used
            as the tag name.
          example: resource_name
          type: string
      type: object
    SpansMetricType:
      default: spans_metrics
      description: The type of resource. The value should always be spans_metrics.
      enum:
      - spans_metrics
      example: spans_metrics
      type: string
      x-enum-varnames:
      - SPANS_METRICS
    SpansMetricCreateAttributes:
      description: The object describing the Datadog span-based metric to create.
      properties:
        compute:
          $ref: '#/components/schemas/SpansMetricCompute'
        filter:
          $ref: '#/components/schemas/SpansMetricFilter'
        group_by:
          description: The rules for the group by.
          items:
            $ref: '#/components/schemas/SpansMetricGroupBy'
          type: array
      required:
      - compute
      type: object
    SpansMetricUpdateAttributes:
      description: The span-based metric properties that will be updated.
      properties:
        compute:
          $ref: '#/components/schemas/SpansMetricUpdateCompute'
        filter:
          $ref: '#/components/schemas/SpansMetricFilter'
        group_by:
          description: The rules for the group by.
          items:
            $ref: '#/components/schemas/SpansMetricGroupBy'
          type: array
      type: object
    SpansMetricUpdateCompute:
      description: The compute rule to compute the span-based metric.
      properties:
        include_percentiles:
          $ref: '#/components/schemas/SpansMetricComputeIncludePercentiles'
      type: object
    SpansMetricResponseCompute:
      description: The compute rule to compute the span-based metric.
      properties:
        aggregation_type:
          $ref: '#/components/schemas/SpansMetricComputeAggregationType'
        include_percentiles:
          $ref: '#/components/schemas/SpansMetricComputeIncludePercentiles'
        path:
          description: The path to the value the span-based metric will aggregate on (only used if the
            aggregation type is a "distribution").
          example: '@duration'
          type: string
      type: object
    SpansMetricFilter:
      description: The span-based metric filter. Spans matching this filter will be aggregated in this
        metric.
      properties:
        query:
          default: '*'
          description: The search query - following the span search syntax.
          example: '@http.status_code:200 service:my-service'
          type: string
      type: object
    SpansMetricComputeIncludePercentiles:
      description: 'Toggle to include or exclude percentile aggregations for distribution metrics.

        Only present when the `aggregation_type` is `distribution`.'
      example: false
      type: boolean
    SpansMetricGroupBy:
      description: A group by rule.
      properties:
        path:
          description: The path to the value the span-based metric will be aggregated over.
          example: resource_name
          type: string
        tag_name:
          description: Eventual name of the tag that gets created. By default, the path attribute is used
            as the tag name.
          example: resource_name
          type: string
      required:
      - path
      type: object
    SpansMetricCompute:
      description: The compute rule to compute the span-based metric.
      properties:
        aggregation_type:
          $ref: '#/components/schemas/SpansMetricComputeAggregationType'
        include_percentiles:
          $ref: '#/components/schemas/SpansMetricComputeIncludePercentiles'
        path:
          description: The path to the value the span-based metric will aggregate on (only used if the
            aggregation type is a "distribution").
          example: '@duration'
          type: string
      required:
      - aggregation_type
      type: object
    SpansMetricComputeAggregationType:
      description: The type of aggregation to use.
      enum:
      - count
      - distribution
      example: distribution
      type: string
      x-enum-varnames:
      - COUNT
      - DISTRIBUTION
  responses:
    NotFoundResponse:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/APIErrorResponse'
      description: Not Found
    BadRequestResponse:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/APIErrorResponse'
      description: Bad Request
    NotAuthorizedResponse:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/APIErrorResponse'
      description: Not Authorized
    ConflictResponse:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/APIErrorResponse'
      description: Conflict
    TooManyRequestsResponse:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/APIErrorResponse'
      description: Too many requests
  parameters:
    SpansMetricIDParameter:
      description: The name of the span-based metric.
      in: path
      name: metric_id
      required: true
      schema:
        type: string
  securitySchemes:
    AuthZ:
      description: This API uses OAuth 2 with the implicit grant flow.
      flows:
        authorizationCode:
          authorizationUrl: /oauth2/v1/authorize
          scopes:
            ai_gateway_config_read: View AI Gateway configuration.
            ai_gateway_config_write: Create, update, and delete AI Gateway configuration.
            ai_gateway_usage: Use AI Gateway and view configuration applicable to the authenticated user.
            apm_api_catalog_read: View API catalog and API definitions.
            apm_api_catalog_write: Add, modify, and delete API catalog definitions.
            apm_read: Read and query APM and Trace Analytics.
            apm_service_catalog_read: View service catalog and service definitions.
            apm_service_catalog_write: Add, modify, and delete service catalog definitions when those
              definitions are maintained by Datadog.
            appsec_vm_read: View infrastructure, application code, and library vulnerability findings.
            aws_configurations_manage: Manage AWS integration account configurations and related integration
              settings.
            billing_edit: Edit your organization's billing information.
            billing_read: View your organization's billing information.
            bits_investigations_read: View Bits AI investigations.
            bits_investigations_write: Create and manage Bits AI investigations.
            cases_read: View Cases.
            cases_shared_settings_write: Update shared case management settings.
            cases_write: Create and update cases.
            ci_visibility_pipelines_write: Create CI Visibility pipeline spans using the API.
            ci_visibility_read: View CI Visibility.
            cloud_cost_management_read: View Cloud Cost pages and the cloud cost data source in dashboards
              and notebooks. For more details, see the Cloud Cost Management docs.
            cloud_cost_management_write: Configure cloud cost accounts and global customizations. For
              more details, see the Cloud Cost Management docs.
            code_analysis_read: View Code Analysis.
            code_coverage_read: View Code Coverage.
            continuous_profiler_pgo_read: Read and query Continuous Profiler data for Profile-Guided Optimization
              (PGO).
            coterm_read: Read terminal recordings.
            coterm_write: Write terminal recordings.
            create_webhooks: Create webhooks integrations.
            dashboards_embed_share: Create, modify, and delete shared dashboards with share type 'embed'.
            dashboards_invite_share: Create, modify, and delete shared dashboards with share type 'invite'.
            dashboards_public_share: Generate public and authenticated links to share dashboards or embeddable
              graphs externally.
            dashboards_read: View dashboards.
            dashboards_write: Create and change dashboards.
            data_scanner_read: View Data Scanner configurations.
            data_scanner_write: Edit Data Scanner configurations.
            embeddable_graphs_share: Generate public links to share embeddable graphs externally.
            error_tracking_read: Read Error Tracking data.
            error_tracking_write: Edit Error Tracking issues.
            event_correlation_config_read: View event correlation configurations.
            event_correlation_config_write: Create and update event correlation configurations.
            events_read: Read Events data.
            hosts_read: List hosts and their attributes.
            incident_notification_settings_read: View Incident Notification Rule Settings.
            incident_notification_settings_write: Configure Incidents Notification Rule settings.
            incident_read: View incidents in Datadog.
            incident_settings_read: View Incident Settings.
            incident_settings_write: Configure Incident Settings.
            incident_write: Create, view, and manage incidents in Datadog.
            integrations_read: View configured integrations and their settings.
            logs_modify_indexes: Modify log indexes, filters, exclusion filters, and configurations.
            logs_read_data: Read log data.
            logs_read_index_data: Read indexed log data.
            manage_integrations: Install, uninstall, and configure integrations.
            metrics_read: View custom metrics.
            monitors_downtime: Set downtimes to suppress alerts from any monitor in an organization. Mute
              and unmute monitors. The ability to write monitors is not required to set downtimes.
            monitors_read: View monitors.
            monitors_write: Edit, delete, and resolve individual monitors.
            network_connections_read: Read cloud network connections.
            org_connections_read: Read cross organization connections.
            org_connections_write: Create, edit, and delete cross organization connections.
            org_management: Edit org configurations, including authentication and certain security preferences
              such as configuring SAML, renaming an org, configuring allowed login methods, creating child
              orgs, subscribing & unsubscribing from apps in the marketplace, and enabling & disabling
              Remote Configuration for the entire organization.
            security_comments_read: Read comments of vulnerabilities.
            security_monitoring_critical_assets_read: Read Critical Assets.
            security_monitoring_critical_assets_write: Write Critical Assets.
            security_monitoring_filters_read: Read Security Filters.
            security_monitoring_filters_write: Create, edit, and delete Security Filters.
            security_monitoring_findings_read: View a list of findings that include both misconfigurations
              and identity risks.
            security_monitoring_rules_read: Read Detection Rules.
            security_monitoring_rules_write: Create and edit Detection Rules.
            security_monitoring_signals_read: View Security Signals.
            security_monitoring_suppressions_read: Read Rule Suppressions.
            security_monitoring_suppressions_write: Write Rule Suppressions.
            security_pipelines_read: View Security Pipelines.
            security_pipelines_write: Create, edit, and delete CSM Security Pipelines.
            siem_entities_read: View Cloud SIEM entities.
            slos_corrections: Apply, edit, and delete SLO status corrections. A user with this permission
              can make status corrections, even if they do not have permission to edit those SLOs.
            slos_read: View SLOs and status corrections.
            slos_write: Create, edit, and delete SLOs.
            synthetics_global_variable_read: View, search, and use Synthetics global variables.
            synthetics_global_variable_write: Create, edit, and delete global variables for Synthetics.
            synthetics_private_location_read: View, search, and use Synthetics private locations.
            synthetics_private_location_write: Create and delete private locations in addition to having
              access to the associated installation guidelines.
            synthetics_read: List and view configured Synthetic tests and test results.
            synthetics_write: Create, edit, and delete Synthetic tests.
            teams_manage: Manage Teams. Create, delete, rename, and edit metadata of all Teams. To control
              Team membership across all Teams, use the User Access Manage permission.
            teams_read: Read Teams data. A User with this permission can view Team names, metadata, and
              which Users are on each Team.
            test_optimization_read: View Test Optimization.
            test_optimization_settings_write: Update service settings in Test Optimization.
            test_optimization_write: Update flaky tests from Flaky Tests Management of Test Optimization.
            timeseries_query: Query Timeseries data.
            usage_read: View your organization's usage and usage attribution.
            user_access_invite: Invite other users to your organization.
            user_access_manage: Disable users, manage user roles, manage SAML-to-role mappings, and configure
              logs restriction queries.
            user_access_read: View users and their roles and settings.
            workflows_read: View workflows.
            workflows_run: Run workflows.
            workflows_write: Create, edit, and delete workflows.
          tokenUrl: /oauth2/v1/token
      type: oauth2
    apiKeyAuth:
      description: Your Datadog API Key.
      in: header
      name: DD-API-KEY
      type: apiKey
      x-env-name: DD_API_KEY
    appKeyAuth:
      description: Your Datadog APP Key.
      in: header
      name: DD-APPLICATION-KEY
      type: apiKey
      x-env-name: DD_APP_KEY
    bearerAuth:
      scheme: bearer
      type: http
      x-env-name: DD_BEARER_TOKEN