---
title: "List project traces"
method: POST
path: "/v1/projects/{projectSlug}/traces/list"
tags: ["Traces"]
---

# List project traces

`POST /v1/projects/{projectSlug}/traces/list`

Returns a cursor-paginated page of traces in the project. Combine `filters` with `query` (free-text semantic search) to narrow the result set. Trace list rows exclude per-message LLM content — use `getTrace` for the full conversation view.

## Path parameters

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

## Request body

- ListTracesBody
  - `cursor` string — Opaque cursor returned in a previous response's `nextCursor`. Omit on the first page.
  - `limit` integer — Page size. Defaults to 50; max 200.
  - `sortBy` 'relevance' | 'startTime' | 'endTime' | 'durationNs' | 'tokensTotal' | 'costTotalMicrocents' — Field to sort by. Defaults to `startTime`. Pass `relevance` together with `query` to rank by semantic match (best match first, then most recent).
  - `sortDirection` 'asc' | 'desc' — Sort direction. Defaults to `desc` (most recent first).
  - `query` string — Free-text semantic search across the trace's input and output messages. Combined with `filters` via AND.
  - `filters` TraceFilterSet — Filter set keyed by trace field. Each entry holds an array of conditions ANDed together for that field; field-level groups are ANDed across the set. Valid fields: status, name, traceId, sessionId, simulationId, userId, tags, models, providers, serviceNames, tools, definedTools, duration, ttft, cost, spanCount, errorCount, tokensInput, tokensOutput, cacheHitRate, startTime, endTime; score-derived keys (score.passed, score.errored, score.value, score.source, score.sourceId, score.annotatorId, score.signalId, score.simulationId); and arbitrary metadata via `metadata.<key>`. `startTime`/`endTime` take ISO-8601 values (a trace's first span start / last span end). `gtePercentile` is only supported on duration/ttft/cost — not on time fields. Unknown fields are rejected rather than ignored.

## Response `200`

Page of traces

- PaginatedTraces
  - `items` Trace[], required — Page of items, in the requested sort order.
    - `organizationId` string, required — Organization that owns this trace.
    - `projectId` string, required — Project this trace belongs to.
    - `traceId` string, required — 32-character trace identifier.
    - `spanCount` integer, required — Total number of spans in the trace.
    - `errorCount` integer, required — Number of spans flagged with an error status.
    - `startTime` string, required — ISO-8601 timestamp of the trace's earliest span.
    - `endTime` string, required — ISO-8601 timestamp of the trace's latest span.
    - `durationNs` number, required — Wall-clock duration of the trace in nanoseconds.
    - `timeToFirstTokenNs` number, required — Nanoseconds from the start of the first LLM span to its first emitted token. `0` if not measured.
    - `tokensInput` number, required — Total input tokens across LLM spans.
    - `tokensOutput` number, required — Total output tokens across LLM spans.
    - `tokensCacheRead` number, required — Total tokens served from the provider's prompt cache.
    - `tokensCacheCreate` number, required — Total tokens written to the provider's prompt cache.
    - `tokensReasoning` number, required — Total reasoning tokens reported by the model.
    - `tokensTotal` number, required — Sum of all token counters.
    - `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).
    - `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 trace. `null` when not a simulation.
    - `tags` string[], required — Free-form tags attached at ingest time.
    - `models` string[], required — Model identifiers seen across the trace's LLM spans.
    - `providers` string[], required — LLM-provider identifiers seen across the trace's spans.
    - `serviceNames` string[], required — OpenTelemetry `service.name` values seen in the trace.
    - `rootSpanId` string, nullable, required — Identifier of the trace's root span. `null` when no root span has been ingested.
    - `rootSpanName` string, nullable, required — `name` attribute of the root span. `null` when no root span has been ingested.
    - `positiveAnnotationCount` integer, required — Number of `passed = true` annotations attached to this trace.
    - `negativeAnnotationCount` integer, required — Number of `passed = false` annotations attached to this trace.
  - `nextCursor` string, nullable, required — Opaque cursor for fetching the next page. `null` when there are no more pages. Pass it back in `cursor` to continue.
  - `hasMore` boolean, required — `true` when there is at least one more page after this one.

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