# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Datadog APM — APM, and Service Definitions (API v2) Spans API
  version: 1.0.0
extends: openapi/datadog-apm-spans-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-09-26'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 3
- target: $.paths['/api/v2/spans/analytics/aggregate'].post
  update:
    x-apievangelist-phrasing:
      intent: Aggregate spans into metrics and timeseries
      effect: read
      questions:
      - Can I compute p95 latency per service from my spans over a time range?
      - How do I bucket spans and count them as a timeseries?
      - What's the hourly request limit on span aggregation in Datadog?
      instructions:
      - text: Aggregate spans using {aggregation} and return the computed buckets.
        slots:
          aggregation: requestBody.data
      - text: Count error spans grouped by service as a timeseries for the last day.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/spans/events'].get
  update:
    x-apievangelist-phrasing:
      intent: List recent spans matching a query
      effect: read
      questions:
      - What are the latest spans for a service in the last 15 minutes?
      - Can I pull spans with a simple query string and time range in the URL?
      instructions:
      - text: Get the latest spans matching {query} from {from} to {to}.
        slots:
          query: query.filter[query]
          from: query.filter[from]
          to: query.filter[to]
      - text: List up to {limit} of my most recent spans.
        slots:
          limit: query.page[limit]
      - text: Fetch the next page of spans after cursor {cursor}.
        slots:
          cursor: query.page[cursor]
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/spans/events/search'].post
  update:
    x-apievangelist-phrasing:
      intent: Search spans with a complex filter body
      effect: read
      questions:
      - How do I run an advanced span search with a full filter object in the request body?
      - Which spans match a complex search across several attributes?
      instructions:
      - text: Search spans using the filter body {search}.
        slots:
          search: requestBody.data
      - text: Run a complex span search for slow checkout requests with errors, sorted by duration.
      method: generated
      generated: '2026-09-26'