v64

latestOpenAPI 3.1.0raw.githubusercontent.com2026-08-03124241726.5 KB

Spans

Query spans across traces

Returns a cursor-paginated page of spans across all traces in the project matching filters (and an optional time range). The span-grain, row-level complement to queryAnalytics with stream: "spans" (which returns aggregates): use this to drill from an aggregate into the individual spans behind it — e.g. every failing search_docs tool span, or the slowest embedding calls.

post/v1/projects/{projectSlug}/spans/query

Path parameters

projectSlugstring required

Project slug (human-readable identifier)

Request body

filtersobject

Row-local span filter set (same DSL as listTraces) over span fields — operation, toolName, model, provider, sessionId, traceId, tags, status (error/ok/unset), duration, cost, tokensInput/tokensOutput. gtePercentile is not supported — use absolute thresholds or a percentile metric.

cursorstring

Opaque cursor from a previous response's nextCursor. Omit on the first page.

limitinteger

Page size. Defaults to 50; max 200.

Example request

{
  "range": {
    "fromIso": "2026-06-23T00:00:00Z",
    "toIso": "2026-06-30T00:00:00Z"
  }
}

Response

Page of spans

nextCursorstring nullable required

Cursor for the next page, or null when there are no more spans.

hasMoreboolean required

Whether more spans match beyond this page.