Skip to main content
Version: v2.0

Query Spans

POST 
/spans/query

Query spans as a flat list.

Thin wrapper over the shared span-query backend that forces focus = "span". Use this when you want a paged list of spans regardless of trace hierarchy — for example, to surface all LLM calls across traces or to stream spans into an external system.

Request body​

  • filtering — span-level conditions (fields on Span and attributes paths).
  • windowing — cursor pagination and time range (see Query Pattern).
  • query_ref, query_variant_ref, query_revision_ref — resolve filtering and windowing from a saved query revision. If the revision's stored formatting.focus is trace, this endpoint returns 409 — call POST /traces/query for that revision.

Response​

Returns {count, spans, windowing}. One response holds at most one page: 100 spans when windowing.limit is not set, and never more than 1000 (the server settings AGENTA_API_TRACING_QUERY_DEFAULT_LIMIT and AGENTA_API_TRACING_QUERY_MAX_LIMIT). windowing is present when the page is full: send it as windowing to read the next page.

Span attributes leave out ag.data.parameters.agent.skills (the skill text of an agent run). GET /spans/{trace_id}/{span_id}, GET /traces/{trace_id} and a query that filters only on trace_id return it.

For the nested per-trace shape, call POST /traces/query or POST /tracing/spans/query with focus="trace" instead.

Request​

Responses​

Successful Response