Sessions API

The Sessions API lets you launch investigations, send follow-up questions, and fetch results programmatically. Sessions are the same investigation primitive that powers the Traversal web application — anything a member can do in the UI, you can do over the API. All endpoints require authentication — see Authentication to create an API key. For base URL, error envelope, and generic status codes, see the API overview.

The V1 Sessions API must be explicitly enabled for your organization. If your organization does not yet have access, contact your Traversal point of contact or support@traversal.com.

Endpoints

See the Endpoints section in the sidebar for the full API reference, generated from the OpenAPI spec.

Required roles

API keys inherit the role of the user who created them. Most Sessions endpoints work for any member, but GET /v1/sessions is admin-only because it returns sessions across the whole organization.

Endpoint	Minimum role
`POST /v1/sessions` — Create a session	`member`
`GET /v1/sessions` — List sessions	`admin`
`GET /v1/sessions/{session_id}` — Get a session	`member`
`GET /v1/sessions/{session_id}/events` — Stream session status	`member`
`POST /v1/sessions/{session_id}/messages` — Send a follow-up	`member`

A request from an underprivileged key returns 403 Forbidden with a message naming the required role. If GET /v1/sessions is failing for you, check the role of the user who issued the key in Settings > User Management.

Investigation depth

Both POST /v1/sessions and POST /v1/sessions/{session_id}/messages accept an optional thinking_mode field that controls how much depth Traversal applies:

Mode	Behavior
`auto` (default)	Traversal classifies the request and picks an appropriate depth.
`deep`	Forces a thorough root-cause analysis.
`fast`	Runs a quick, exploratory pass.

If omitted, thinking_mode defaults to auto, so existing integrations need no changes.

curl -X POST https://api.traversal.com/v1/sessions \
  -H "Authorization: Bearer $TRAVERSAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "Checkout latency spiked at 14:30 UTC",
    "idempotency_key": "pagerduty-incident-P12345",
    "thinking_mode": "deep"
  }'

Session lifecycle

Investigations are asynchronous. Creating a session or sending a follow-up returns immediately while 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

Status	Meaning
`running`	A new investigation is in progress.
`idle`	Investigation is complete and ready for follow-ups.
`follow_up_running`	A follow-up message is being processed.
`failed`	The investigation or follow-up errored or timed out.
`cancelled`	The investigation was cancelled.

idle, failed, and cancelled are terminal statuses. Once the session reaches one of these states, 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 request text/event-stream:

curl --no-buffer \
  -H "Authorization: Bearer $TRAVERSAL_API_KEY" \
  -H "Accept: text/event-stream" \
  https://api.traversal.com/v1/sessions/$SESSION_ID/events

The stream sends a named status event when you connect and whenever the status changes:

event: status
data: {"id":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","status":"running","title":"Elevated error rate in checkout service","input":"Checkout latency spiked at 14:30 UTC","created_at":"2026-08-10T14:35:00Z","updated_at":"2026-08-10T14:35:00Z","messages":null}

: keepalive

event: status
data: {"id":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","status":"idle","title":"Elevated error rate in checkout service","input":"Checkout latency spiked at 14:30 UTC","created_at":"2026-08-10T14:35:00Z","updated_at":"2026-08-10T14:38:12Z","messages":null}

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.

If the connection closes before you receive a terminal status, reconnect to the same endpoint. The first event always contains the current status, so you do not need an event cursor or Last-Event-ID header.

Python example

The following example creates an investigation, waits on the event stream, and retrieves the final messages:

import json
import os

import requests

base_url = "https://api.traversal.com"
headers = {"Authorization": f"Bearer {os.environ['TRAVERSAL_API_KEY']}"}

create_response = requests.post(
    f"{base_url}/v1/sessions",
    headers=headers,
    json={
        "input": "Checkout latency spiked at 14:30 UTC",
        "idempotency_key": "pagerduty-incident-P12345",
    },
)
create_response.raise_for_status()
created = create_response.json()

with requests.get(
    f"{base_url}/v1/sessions/{created['id']}/events",
    headers={**headers, "Accept": "text/event-stream"},
    stream=True,
    timeout=(10, 30),
) as response:
    response.raise_for_status()
    for line in response.iter_lines(chunk_size=1, decode_unicode=True):
        if not line.startswith("data: "):
            continue
        session = json.loads(line.removeprefix("data: "))
        if session["status"] in {"idle", "failed", "cancelled"}:
            break

result_response = requests.get(
    f"{base_url}/v1/sessions/{created['id']}",
    headers=headers,
)
result_response.raise_for_status()
result = result_response.json()

Set a read timeout longer than the 15-second keepalive interval. If your client raises a timeout or the connection drops, reconnect and continue waiting.

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.

Investigations have a 1-hour server-side timeout. If an investigation has not completed within that window, the session status transitions to failed.

Session-specific errors

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

Status code	Meaning	When it occurs
`404`	Not Found	Session does not exist or does not belong to your organization. This validation happens before the event stream opens.
`409`	Conflict	Session is not `idle` (e.g., still `running` or `follow_up_running`). Includes `retry_after`.
`429`	Too Many Requests	Organization has reached the limit of 15 concurrent running sessions. Both new investigations (`POST /v1/sessions`) and in-flight follow-ups (`POST /v1/sessions/{id}/messages`) count toward this limit. Includes `retry_after` (default 30s).

Get Started

Architecture

Set up

Using Traversal

API

Security & Trust

Changelog

Endpoints

Required roles

Investigation depth

Session lifecycle

Status values

Status transitions

Stream status updates

Python example

Polling fallback

Session-specific errors

​Endpoints

​Required roles

​Investigation depth

​Session lifecycle

​Status values

​Status transitions

​Stream status updates

​Python example

​Polling fallback

​Session-specific errors

Endpoints

Required roles

Investigation depth

Session lifecycle

Status values

Status transitions

Stream status updates

Python example

Polling fallback

Session-specific errors