Sessions

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. When the agent is configured for reasoning, sessions also track reasoning configuration per run. Sessions persist until explicitly deleted.

Common Patterns

Sessions are created automatically when you run an agent without a session_id, or explicitly with POST /api/agents/{id}/sessions. 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.

Every route on this page accepts the service role key or a signed-in user’s access token. An end user can read and delete only their own sessions; anyone else’s session, or one your backend created without a user_id, answers 404. See Which key for which route.

GET /api/sessions/

Get a session by ID.

string

required

Session ID

response = requests.get(f"{BASE_URL}/api/sessions/{session_id}", headers=headers)

const res = await fetch(`${BASE_URL}/api/sessions/${sessionId}`, { headers });

curl '{BASE_URL}/api/sessions/{id}' -H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}"

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.

string

required

Session ID

response = requests.get(f"{BASE_URL}/api/sessions/{session_id}/messages", headers=headers)

const res = await fetch(`${BASE_URL}/api/sessions/${sessionId}/messages`, { headers });

curl '{BASE_URL}/api/sessions/{id}/messages' -H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}"

GET /api/sessions//runs

List all agent runs within a session.

string

required

Session ID

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

const res = await fetch(`${BASE_URL}/api/sessions/${sessionId}/runs`, { headers });

curl '{BASE_URL}/api/sessions/{id}/runs' -H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}"

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 which chunks the agent saw before generating a given turn, separate from the assembled /messages view.

string

required

Session 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)

const res = await fetch(`${BASE_URL}/api/sessions/${sessionId}/runs/${runId}/retrieved-context`, { headers });

curl '{BASE_URL}/api/sessions/{id}/runs/{run_id}/retrieved-context' -H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}"

DELETE /api/sessions/

Delete a session and all its runs.

string

required

Session ID

response = requests.delete(f"{BASE_URL}/api/sessions/{session_id}", headers=headers)

await fetch(`${BASE_URL}/api/sessions/${sessionId}`, { method: "DELETE", headers });

curl -X DELETE '{BASE_URL}/api/sessions/{id}' -H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}"

Error Responses

Errors return {"error": "<message>"}.

Status	Description
400	The session id isn’t a string of at most 255 characters
401	Missing or invalid bearer token; an end-user token without a UUID `sub` or an `exp`
404	No session exists with the given ID, or (with an end user’s token) the session isn’t that user’s (returned as 404 to avoid leaking existence)
404	The given run does not exist within this session (`/runs/{run_id}/retrieved-context`)

Getting Started

Concepts

Guides

API Reference

Common Patterns

GET /api/sessions/

GET /api/sessions//messages

GET /api/sessions//runs

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

DELETE /api/sessions/

Error Responses

​Common Patterns

​GET /api/sessions/

​GET /api/sessions//messages

​GET /api/sessions//runs

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

​DELETE /api/sessions/

​Error Responses

Common Patterns

GET /api/sessions/

GET /api/sessions//messages

GET /api/sessions//runs

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

DELETE /api/sessions/

Error Responses