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

# List project sessions

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

Returns a cursor-paginated page of sessions in the project. A session groups the traces of one conversation. Combine `filters` with `query` (free-text semantic search) to narrow the result set. Session list rows exclude per-message LLM content — use `getSession` for the conversation view.

## Path parameters

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

## Request body

- ListSessionsBody
  - `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` 'lastActivity' | 'startTime' | 'duration' | 'ttft' | 'cost' | 'spans' | 'traceCount' — Field to sort by. Defaults to `lastActivity` (most recently active first).
  - `sortDirection` 'asc' | 'desc' — Sort direction. Defaults to `desc` (most recent first).
  - `query` string — Free-text semantic search across the sessions' traces (input and output messages). Combined with `filters` via AND.
  - `filters` SessionFilterSet — Filter set keyed by session 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, moments, topics, 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>`. `moments` filters by conversation moment kind and `topics` by behavior topic id (a topic matches its whole subtree). `startTime`/`endTime` take ISO-8601 values (a session's first span start / last span end). `gtePercentile` is only supported on duration/ttft/cost. Unknown fields are rejected rather than ignored.

## Response `200`

Page of sessions

- PaginatedSessions
  - `items` Session[], required — Page of items, in the requested sort order.
    - `organizationId` string, required — Organization that owns this session.
    - `projectId` string, required — Project this session belongs to.
    - `sessionId` string, required — Session identifier set by the SDK. Groups the traces of one conversation.
    - `traceCount` integer, required — Number of traces in the session.
    - `traceIds` string[], required — Identifiers of the traces that make up the session.
    - `spanCount` integer, required — Total number of spans across the session's traces.
    - `errorCount` integer, required — Number of spans flagged with an error status.
    - `startTime` string, required — ISO-8601 timestamp of the session's earliest span.
    - `endTime` string, required — ISO-8601 timestamp of the session's latest span.
    - `lastActivityTime` string, required — ISO-8601 timestamp of the session's most recent span start.
    - `durationNs` number, required — Active execution time of the session in nanoseconds, not wall-clock.
    - `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 the session's LLM spans.
    - `tokensOutput` number, required — Total output tokens across the session's 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).
    - `userId` string, nullable, required — End-user identifier set by the SDK. `null` when absent.
    - `userEmail` string, nullable, required — End-user email set by the SDK. `null` when absent.
    - `simulationId` string, nullable, required — CUID of the simulation that produced this session. `null` when not a simulation.
    - `tags` string[], required — Free-form tags attached at ingest time.
    - `metadata` object, required — Free-form metadata attached at ingest time.
    - `models` string[], required — Model identifiers seen across the session's LLM spans.
    - `providers` string[], required — LLM-provider identifiers seen across the session's spans.
    - `serviceNames` string[], required — OpenTelemetry `service.name` values seen in the session.
    - `agentNames` string[], required — Agent names seen across the session's spans.
    - `definedTools` string[], required — Tool names declared available across the session's spans.
    - `rootSpanId` string, nullable, required — Identifier of the session'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.
  - `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/revisions/a0bf72a85607/schema)