v4

latestOpenAPI 3.1.02026-08-086635375.7 KB

Sessions

get session

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.

get/v1/sessions/{id}

Path parameters

idstring uuid required

Session ID

Response

Successfully retrieved session

idstring uuid

Unique identifier for the session.

personaIdstring uuid nullable

ID of the persona the client connected to, or null if the session was issued with an ephemeral persona config.

clientLabelstring nullable

Label supplied by the caller when minting the session token.

startTimestring date-time

Timestamp when the session started.

endTimestring date-time nullable

Timestamp when the session ended, or null if still active.

sessionLengthMsinteger nullable

Duration of the session in milliseconds, or null if still active.

exitStatusstring 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.

engineHoststring nullable

Hostname of the engine pod that served the session.

engineProtocolstring nullable

Protocol used to stream the session (e.g. https).

engineVersionstring nullable

Version of the engine pod that served the session.

clientMetadataobject

Arbitrary metadata collected from the client during the session.

personaConfigobject

Snapshot of the persona configuration taken at the moment the session started.

apiKeyIdstring uuid nullable

ID of the API key that minted the session token.

organizationIdstring

ID of the organization that owns the session. IDs may be either UUIDs or nanoid-style strings depending on when the organization was created.

createdAtstring date-time

Timestamp when the session record was created.

updatedAtstring date-time nullable

Timestamp when the session record was last updated.