---
title: "get session"
method: GET
path: "/v1/sessions/{id}"
tags: ["Sessions"]
---

# get session

`GET /v1/sessions/{id}`

Returns a session by ID, including the tool calls made during the session once it has ended and the engine has delivered its session report (`toolCalls` is empty until then, and always empty for LiveKit and audio-passthrough sessions, which never produce a report). Tool call names, timing, status and errors are always included; call arguments, results and accessed-document names are only included when transcripts were enabled for the session and the session is not zero-data-retention, since they embed conversation content. HTTP headers and credential-like keys are never returned. Anam-internal admin API keys may fetch sessions of any organization.

## Path parameters

- `id` string, uuid, required

## Response `200`

Successfully retrieved session

- object — A single connection between a client and a persona. Contains metadata but not the transcript or recording — those are fetched separately.
  - `id` string, uuid — Unique identifier for the session.
  - `personaId` string, uuid, nullable — ID of the persona the client connected to, or `null` if the session was issued with an ephemeral persona config.
  - `clientLabel` string, nullable — Label supplied by the caller when minting the session token.
  - `startTime` string, date-time — Timestamp when the session started.
  - `endTime` string, date-time, nullable — Timestamp when the session ended, or `null` if still active.
  - `sessionLengthMs` integer, nullable — Duration of the session in milliseconds, or `null` if still active.
  - `exitStatus` string, nullable — How the session ended, or `null` if still active. Currently one of `CLOSED_BY_ENGINE` (the engine closed the session; this value does not distinguish the underlying outcome), `FAILED_TO_START`, `FAILED_PENDING_TIMEOUT`, `ORPHANED_NO_END_SIGNAL`, `CLOSED_DANGLING_SESSION`, `HOST_FAILED_HEALTH_CHECK` or `HOST_UNREGISTERED`. Treat this as an open string set — new values may be added over time, so clients should handle unrecognised values gracefully rather than exhaustively matching.
  - `engineHost` string, nullable — Hostname of the engine pod that served the session.
  - `engineProtocol` string, nullable — Protocol used to stream the session (e.g. `https`).
  - `engineVersion` string, nullable — Version of the engine pod that served the session.
  - `clientMetadata` object — Arbitrary metadata collected from the client during the session.
  - `personaConfig` object — Snapshot of the persona configuration taken at the moment the session started.
  - `apiKeyId` string, uuid, nullable — ID of the API key that minted the session token.
  - `organizationId` string — ID of the organization that owns the session. IDs may be either UUIDs or nanoid-style strings depending on when the organization was created.
  - `createdAt` string, date-time — Timestamp when the session record was created.
  - `updatedAt` string, date-time, nullable — Timestamp when the session record was last updated.
  - `toolCalls` SessionToolCallDetail[] — Tool calls made during the session, in conversational order. Empty until the session has ended and its report has been delivered.
    - `turnIndex` integer — Index of the conversational turn the call belongs to, matching `turns[].turnIndex` on GET /v1/sessions/{id}/analytics.
    - `correlationId` string, nullable — The user action correlation ID shared by SDK events for this turn.
    - `toolCallId` string, nullable — The engine's ID for this tool call, matching the ID surfaced in SDK tool events.
    - `toolName` string, nullable
    - `toolType` 'server' | 'client' | 'system' | 'null', nullable
    - `toolSubtype` string, nullable — For server tools, distinguishes e.g. `rag` from `webhook`.
    - `status` 'started' | 'completed' | 'failed' | 'null', nullable
    - `startedAt` string, date-time, nullable
    - `completedAt` string, date-time, nullable
    - `durationSeconds` number, nullable
    - `errorMessage` string, nullable
    - `arguments` object, nullable — The arguments the LLM called the tool with. Null when the session has transcripts disabled or is zero-data-retention. Values under header- or credential-like keys are replaced with `[REDACTED]`.
    - `result` string, nullable — The result the tool returned to the LLM. Null when the session has transcripts disabled or is zero-data-retention, and for calls that produced no result (e.g. failed or fire-and-forget client calls).
    - `documentsAccessed` string[], nullable — For knowledge (RAG) tools, the names of the documents the call read. Null under the same conditions as `arguments`.

## Other responses

- `400` — Bad request - Invalid session ID
- `401` — Unauthorized - Invalid or missing API key
- `403` — Forbidden - API key lacks the required permission
- `404` — Not Found - Session not found
- `500` — Server error

---

[API](https://skmtc.net/anam/apis/anam-ai-api.md) · [All operations](https://skmtc.net/anam/apis/anam-ai-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/anam/anam-ai-api/versions/67afd1c5db59/schema)