Skip to main content
A session is the top-level container for a traced agent research conversation. Every tool call, reasoning step, and run belongs to a session. The web UI renders sessions as replayable timelines.

​
List sessions

GET /api/sessions
Authorization: Bearer <token>
Returns sessions for the caller’s tenant, newest first.

​
Response

{
  "sessions": [
    {
      "id": "sess_abc",
      "title": "NVDA momentum research",
      "tenant_id": "tnt_abc",
      "created_at": "2025-01-15T12:00:00Z",
      "closed_at": null,
      "event_count": 42
    }
  ]
}

​
Create a session

POST /api/sessions
Authorization: Bearer <token>
Content-Type: application/json

{
  "title": "NVDA momentum research",
  "prompt": "Research NVDA — pull price history, screen peers, propose a momentum strategy, and backtest it."
}
FieldTypeRequiredDescription
titlestringyesHuman-readable session title.
promptstringnoThe initial prompt that kicked off the session.

​
Response

{
  "id": "sess_abc",
  "title": "NVDA momentum research",
  "prompt": "Research NVDA ...",
  "tenant_id": "tnt_abc",
  "created_at": "2025-01-15T12:00:00Z"
}
Creating a session emits a session_open trace event. The session is then ready to receive tool calls and runs.

​
Seed a demo session

POST /api/sessions/seed-demo
Authorization: Bearer <clerk-jwt>
Seeds a deterministic demo session for first-time users. This is what the web UI’s Welcome page auto-plays so a new user sees a complete research session before they’ve connected an agent.
The demo seeder generates a deterministic NVDA research session. The same events are produced every time, so the replay is identical for every new user. See Session replay.
The demo session includes this event sequence:
  1. session_open
  2. reasoning — agent plans the research
  3. tool_call — fetch_history for NVDA
  4. tool_call — screen_momentum on semis
  5. strategy_proposed — a momentum StrategySpec
  6. tool_call — request_backtest
  7. run_progress — backtest completes
  8. session_close

​
Response

{
  "id": "sess_demo_001",
  "title": "Demo: NVDA momentum research",
  "demo": true,
  "created_at": "2025-01-15T12:00:00Z"
}