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. WhatGET /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.
Investigation depth
BothPOST /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 toGET /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.
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 requesttext/event-stream:
status event when you connect and whenever the status changes:
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:Polling fallback
If your HTTP client or network path does not support streaming responses, pollGET /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.