---
title: "Query spans across traces"
method: POST
path: "/v1/projects/{projectSlug}/spans/query"
tags: ["Spans"]
---

# Query spans across traces

`POST /v1/projects/{projectSlug}/spans/query`

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.

## Path parameters

- `projectSlug` string, required — Project slug (human-readable identifier)

## Request body

- QuerySpansBody
  - `filters` object — 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.
  - `orderBy` object — Sort order. Defaults to newest first (`startTime` desc); use `duration`/`cost` desc for top-N slowest/costliest.
    - `field` 'startTime' | 'duration' | 'cost' — Sort key.
    - `direction` 'asc' | 'desc' — Sort direction.
  - `range` object — Restrict to spans whose `startTime` falls in this window.
    - `fromIso` string, date-time, required — Inclusive lower bound (ISO-8601).
    - `toIso` string, date-time, required — Upper bound (ISO-8601). Must be after `fromIso`.
  - `cursor` string — Opaque cursor from a previous response's `nextCursor`. Omit on the first page.
  - `limit` integer — Page size. Defaults to 50; max 200.

## Response `200`

Page of spans

- QuerySpans
  - `items` Span[], required — Matching spans across traces, newest first. Rows exclude per-message LLM content — use a span point-lookup for the payload.
    - `organizationId` string, required — Organization that owns this span.
    - `projectId` string, required — Project this span belongs to.
    - `traceId` string, required — Identifier of the trace this span belongs to.
    - `spanId` string, required — Stable span identifier within the trace.
    - `parentSpanId` string, nullable, required — Identifier of the parent span. `null` for root spans.
    - `sessionId` string, nullable, required — Conversation/session identifier set by the SDK. `null` when absent.
    - `userId` string, nullable, required — End-user identifier set by the SDK. `null` when absent.
    - `simulationId` string, nullable, required — CUID of the simulation that produced this span. `null` when not a simulation.
    - `apiKeyId` string, nullable, required — Latitude API key used to ingest the span. `null` when ingested without an API key.
    - `startTime` string, required — ISO-8601 timestamp at which the span started.
    - `endTime` string, required — ISO-8601 timestamp at which the span ended.
    - `name` string, required — Span name (e.g. the entry-point function or route).
    - `serviceName` string, required — OpenTelemetry `service.name` of the emitting service.
    - `kind` 'unspecified' | 'internal' | 'server' | 'client' | 'producer' | 'consumer', required — OpenTelemetry span kind.
    - `statusCode` 'unset' | 'ok' | 'error', required — OpenTelemetry span status code.
    - `statusMessage` string, required — OpenTelemetry status message. Empty when not set.
    - `traceFlags` number, required — OpenTelemetry trace flags bitfield.
    - `traceState` string, required — OpenTelemetry trace state (vendor-specific propagation). Empty when not set.
    - `errorType` string, nullable, required — Error class/type label when the span errored. `null` for successful spans.
    - `tags` string[], required — Free-form tags attached at ingest time.
    - `operation` string, required — GenAI operation category (e.g. `"chat"`, `"embeddings"`, `"execute_tool"`, `"invoke_agent"`) or a custom string for non-GenAI spans.
    - `provider` string, nullable, required — LLM provider id. `null` for non-LLM spans.
    - `model` string, nullable, required — Model id as requested. `null` for non-LLM spans.
    - `responseModel` string, nullable, required — Model id reported by the provider's response. `null` for non-LLM spans.
    - `tokensInput` number, required — Input tokens consumed by this span.
    - `tokensOutput` number, required — Output tokens produced by this span.
    - `tokensCacheRead` number, required — Tokens served from the provider's prompt cache.
    - `tokensCacheCreate` number, required — Tokens written to the provider's prompt cache.
    - `tokensReasoning` number, required — Reasoning tokens reported by the model.
    - `costInputMicrocents` number, required — Cost of input tokens in microcents (100,000,000 per USD).
    - `costOutputMicrocents` number, required — Cost of output tokens in microcents (100,000,000 per USD).
    - `costTotalMicrocents` number, required — Total cost in microcents (100,000,000 per USD).
    - `costIsEstimated` boolean, required — `true` when the cost was derived from public pricing tables instead of the provider's bill.
    - `timeToFirstTokenNs` number, required — Nanoseconds from the start of the span to its first emitted token. `0` if not measured.
    - `isStreaming` boolean, required — `true` when the span was produced by a streaming LLM call.
    - `responseId` string, nullable, required — Response identifier returned by the LLM. `null` when the provider didn't return one.
    - `finishReasons` string[], required — Per-choice finish reasons reported by the LLM provider.
    - `scopeName` string, required — OpenTelemetry instrumentation scope name. Empty when not set.
    - `scopeVersion` string, required — OpenTelemetry instrumentation scope version. Empty when not set.
    - `retentionDays` integer — Per-span retention override in days. Omitted when the project default applies.
    - `ingestedAt` string, required — ISO-8601 timestamp at which Latitude received this span.
  - `nextCursor` string, nullable, required — Cursor for the next page, or `null` when there are no more spans.
  - `hasMore` boolean, required — Whether more spans match beyond this page.

## Other responses

- `400` — Validation error
- `401` — Unauthorized
- `404` — Not found

---

[API](https://skmtc.net/latitude-dev/apis/latitude.md) · [All operations](https://skmtc.net/latitude-dev/apis/latitude/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/latitude-dev/latitude/versions/6a8789c59a5c/schema)