Chat Sessions
Chat sessions are persistent conversation threads between a user and an agent. Each session captures the full exchange — messages, tool calls, model responses, and token usage — so you can resume, review, and export your work.
What a session is
Section titled “What a session is”A session belongs to a single user within a workspace and is grouped under a project in that workspace. It records:
- The model used for the conversation
- A running count of messages and tokens
- A timeline of events stored for replay and analysis
Sessions are created automatically when you start a conversation in the CLI or Studio. You can also save, load, and manage sessions explicitly.
Session events
Section titled “Session events”Every interaction within a session is recorded as a typed event. Events are stored in order and include metadata like the model, role, tool name, and token counts.
| Event type | What it captures |
|---|---|
| User message | Text sent by the user |
| Agent response | Model-generated reply |
| Tool call | Tool invocation and its result |
| Generation start | Beginning of a model inference call |
| Generation end | Completion of inference with token counts |
| Heartbeat | Keepalive signal during long-running events |
Events are stored in ClickHouse for efficient querying and are partitioned by month.
Lifecycle
Section titled “Lifecycle”| Action | What happens |
|---|---|
| Create | Session is created when you start a conversation |
| Update | Message and token counts increment as the conversation grows |
| Title | An AI-generated title is produced from the first message |
| Archive | Session is soft-deleted and hidden from listings |
| Delete | Session and all its events are permanently removed |
Managing sessions
Section titled “Managing sessions”Sessions can be managed from the CLI or the API:
- CLI: Use
/save,/load,/sessions,/delete,/export, and/clearduring a conversation. See Chat & Sessions for the full command reference. - API: Sessions are available at workspace-scoped routes like
GET /api/v1/org/{org}/ws/{workspace}/sessions.
The list endpoint supports pagination via page and page_size query parameters.
Workspace and project grouping
Section titled “Workspace and project grouping”Sessions are workspace-owned resources and are always grouped under a concrete project. If the client omits project_id, the API assigns the workspace’s default project automatically.
The API surface is workspace-scoped:
GET /api/v1/org/{org}/ws/{workspace}/sessionsPOST /api/v1/org/{org}/ws/{workspace}/sessionsGET /api/v1/org/{org}/ws/{workspace}/sessions/{session_id}PATCH /api/v1/org/{org}/ws/{workspace}/sessions/{session_id}DELETE /api/v1/org/{org}/ws/{workspace}/sessions/{session_id}POST /api/v1/org/{org}/ws/{workspace}/sessions/{session_id}/eventsGET /api/v1/org/{org}/ws/{workspace}/sessions/{session_id}/events