Skip to main content
The Sessions API lets you start investigations, send follow-up questions, and fetch results from your own tools. A session is the API object for an investigation. All endpoints require authentication. Create an API key first. For the base URL, error envelope, and generic status codes, see the API overview. The sidebar lists every endpoint, generated from the OpenAPI spec.

Required roles

Personal API keys use their owner’s current role. Service-account keys use the account’s current role, not the role of the administrator who created the key. Sessions endpoints require Member. What GET /v1/sessions returns depends on the caller’s role. GET /v1/sessions lists only sessions created through the V1 API, never sessions created in the web app or through chat, and only those in the authenticated organization:
  • Admin personal keys and Admin service-account keys receive every V1 API session in the organization.
  • Member personal keys receive the API sessions their owner created or has viewed. Member service-account keys receive only the API sessions that service account created.
Member-role keys can also retrieve any session in the authenticated organization by ID. Follow-ups require the identity that owns the session. Keys belonging to the same service account share session ownership, so a replacement key can continue that account’s investigations. A key for a different account cannot send follow-ups to those sessions, even if both accounts belong to the same organization.

Investigation depth

Both POST /v1/sessions and POST /v1/sessions/{session_id}/messages accept an optional thinking_mode field that sets how deeply Traversal investigates. See Investigation depth for guidance on choosing a mode. If you omit thinking_mode, the session runs in default.

Deprecated mode names

The API still accepts the earlier mode names. auto and deep run as default, and fast runs as lightning. Use default and lightning in new integrations. The X-Traversal-Thinking-Mode response header shows the mode you requested and the mode the session ran in. It adds deprecated=true when you send a deprecated name:

Session lifecycle

Investigations are asynchronous. Creating a session or sending a follow-up returns immediately, and Traversal investigates in the background. Connect to GET /v1/sessions/{session_id}/events to wait for a terminal status, then retrieve the result with GET /v1/sessions/{session_id}.

Status values

idle, failed, and cancelled are terminal statuses. When a session reaches one, no further work is in progress.
Investigations have a 1-hour server-side timeout. If an investigation hasn’t completed within that window, the session status changes to failed.

Status transitions

Stream status updates

The session events endpoint uses Server-Sent Events to report lifecycle changes without polling. Send the same bearer token you use for other API requests and request text/event-stream:
The stream sends a named status event when you connect and whenever the status changes:
Each data value uses the same session shape as other Sessions endpoints, but messages is always null. Fetch GET /v1/sessions/{session_id} after the terminal event to retrieve the conversation and final result. While the status remains running or follow_up_running, the server sends a : keepalive comment every 15 seconds when there is no status change. SSE clients ignore comment lines automatically. The stream closes after it sends an idle, failed, or cancelled status.

Python example

The following example creates an investigation, waits on the event stream, and retrieves the final messages:
Set a read timeout longer than the 15-second keepalive interval. If your client times out or the connection closes before a terminal status, reconnect to the same endpoint. The first event contains the current status, so you don’t need an event cursor or Last-Event-ID header.

Polling fallback

If your HTTP client or network path does not support streaming responses, poll GET /v1/sessions/{session_id} at a steady interval until the session is no longer running or follow_up_running. A 5-second interval is a reasonable default.

Session-specific errors

In addition to the generic status codes, the Sessions API returns these session-specific responses: