---
title: "List trace spans"
method: GET
path: "/v1/projects/{projectSlug}/traces/{traceId}/spans"
tags: ["Traces"]
---

# List trace spans

`GET /v1/projects/{projectSlug}/traces/{traceId}/spans`

Returns every span belonging to the trace, ordered by `startTime` ascending. Spans carry the OpenTelemetry envelope (kind, status, attributes, resource) plus Latitude's GenAI enrichment (tokens, cost, operation, provider, model). Per-message LLM content is excluded for size; use a span point-lookup for the conversation payload.

## Path parameters

- `projectSlug` string, required — Project slug (human-readable identifier)
- `traceId` string, required — 32-character trace identifier.

## Response `200`

Spans of the trace

- TraceSpans
  - `items` Span[], required — All spans belonging to the trace, ordered by `startTime` ascending.
    - `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.

## 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)