Sessions

Manage multi-turn chat sessions and their message/run history.

Sessions store the conversation history between users and agents. Each session contains messages (user inputs, assistant responses, tool calls, tool results) and can span multiple agent runs. 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

Python

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

GET /api/sessions//messages

Get assembled chat messages for a session.

id · string · required

Session ID

Python

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

Python

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

DELETE /api/sessions/

Delete a session and all its runs.

id · string · required

Session ID

Python

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

Error Responses

Status	Code	Description
404	session_not_found	No session exists with the given ID