Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.traversal.com/llms.txt

Use this file to discover all available pages before exploring further.

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.

​
Session lifecycle

Investigations are asynchronous. Creating a session or sending a follow-up returns immediately while Traversal investigates in the background. To retrieve the result, poll GET /v1/sessions/{session_id} until the session reaches a terminal state.

​
Status values

StatusMeaning
runningA new investigation is in progress.
idleInvestigation is complete and ready for follow-ups.
follow_up_runningA follow-up message is being processed.
failedThe investigation or follow-up errored or timed out.
idle and failed are terminal-for-polling — once the session reaches one of these states, no further work is in progress.

​
Status transitions

After creating a session or sending a follow-up, poll GET /v1/sessions/{session_id} at a steady interval until the session is no longer in running or follow_up_running. 
import time
import requests

def poll_session(base_url, session_id, api_key, interval=5, timeout=3600):
    """Poll until the session reaches a terminal state."""
    headers = {"Authorization": f"Bearer {api_key}"}
    elapsed = 0
    while elapsed < timeout:
        resp = requests.get(f"{base_url}/v1/sessions/{session_id}", headers=headers)
        data = resp.json()
        if data["status"] in ("idle", "failed"):
            return data
        time.sleep(interval)
        elapsed += interval
    raise TimeoutError("Session did not complete within timeout")
A 5-second polling interval is a reasonable default. Investigations typically complete in a few minutes, but complex incidents may take longer.
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 codeMeaningWhen it occurs
404Not FoundSession does not exist or does not belong to your organization.
409ConflictSession is not idle (e.g., still running or follow_up_running). Includes retry_after.
429Too Many RequestsOrganization has reached the limit of 5 concurrent running sessions. Includes retry_after (default 30s).