Skip to main content
Sessions store the conversation history between users and agents. Each session contains messages (user inputs, assistant responses, tool calls, tool results, plus the retrieved context that grounded each assistant turn) and can span multiple agent runs. Sessions also track reasoning configuration on a per-run basis when the agent is configured for reasoning. Sessions persist until explicitly deleted, enabling long-running multi-turn conversations.

​
Common Patterns

Sessions are created automatically when you run an agent without a session_id. To continue a conversation, pass the session_id from the start event of a previous run. Retrieve message history with GET /api/sessions/{id}/messages to display conversation context.

​
GET /api/sessions/

Get a session by ID.
​
id
string
required
Session ID
response = requests.get(f"{BASE_URL}/api/sessions/{session_id}", headers=headers)

​
GET /api/sessions//messages

Get assembled chat messages for a session. Each assistant message includes its retrieved_context (knowledge-base chunks fetched during the run) so you can surface citations alongside replies.
​
id
string
required
Session ID
response = requests.get(f"{BASE_URL}/api/sessions/{session_id}/messages", headers=headers)

​
GET /api/sessions//runs

List all agent runs within a session.
​
id
string
required
Session ID
response = requests.get(f"{BASE_URL}/api/sessions/{session_id}/runs", headers=headers)

​
GET /api/sessions//runs//retrieved-context

Get the retrieved context (knowledge-base chunks fetched during retrieval) for a single run within a session. Useful for debugging RAG behavior — you can see exactly which chunks the agent saw before generating a given turn, separate from the assembled /messages view.
​
id
string
required
Session ID
​
run_id
string
required
Run ID (the run_id of an agent_run belonging to this session)
{
  "session_id": "sess_abc",
  "run_id": "run_xyz",
  "retrieved_context": [
    { "_type": "retrieval_diagnostics", "...": "..." },
    {
      "id": "chunk-uuid",
      "text": "...",
      "score": 0.84,
      "retrieval_score": 0.71,
      "reranker_score": 0.84,
      "source_id": "src-uuid",
      "source_name": "Q3-2025.pdf",
      "knowledge_base_id": "kb-uuid",
      "kb_name": "Finance docs",
      "indexing_strategy": "chunk_embed",
      "meta": {},
      "included_in_context": true
    }
  ]
}

response = requests.get(f"{BASE_URL}/api/sessions/{session_id}/runs/{run_id}/retrieved-context", headers=headers)

​
DELETE /api/sessions/

Delete a session and all its runs.
​
id
string
required
Session ID
response = requests.delete(f"{BASE_URL}/api/sessions/{session_id}", headers=headers)

​
Error Responses

Errors return {"error": "<message>"}.
StatusDescription
404No session exists with the given ID, or the session is owned by another user (returned as 404 to avoid leaking existence)
404The given run does not exist within this session (/runs/{run_id}/retrieved-context)