Sessions & events
Run an agent by creating a session, sending messages, and streaming the agent's events over SSE.
Sessions & events
A session runs an agent; events are the messages on its timeline. This page covers driving a turn end to end.
Create a session
Open an agent and start a session — the Console opens a transcript view where you chat with the agent and watch its events render live.
POST /v1/sessions. The agent field is either a bare id (pins to the latest
version) or { "id": "...", "version": N } to pin a specific version.
curl https://agents.clusterbase.dev/v1/sessions \
-H "Authorization: Bearer $CLUSTER_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "agent": "agt_3f9c2a" }'{
"id": "ses_8b1d4e",
"agent_id": "agt_3f9c2a",
"agent_version": 1,
"status": { "status": "idle" },
"usage": { "input_tokens": 0, "output_tokens": 0 },
"created_at": "2026-06-16T12:00:00Z"
}To give the session VM-backed tools (shell, file, patch), bind it to an
environment with environment_id. To attach MCP
credentials, pass vault_ids — see Vaults & MCP.
Send a message
User events are submitted as a batch under events, so you can send a
message (and, say, a follow-up interrupt) atomically. A turn begins when you
append a user.message.
curl https://agents.clusterbase.dev/v1/sessions/ses_8b1d4e/events \
-H "Authorization: Bearer $CLUSTER_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"events": [
{ "type": "user.message", "content": [{ "type": "text", "text": "Summarize the React 19 release notes." }] }
]
}'Stream the response
GET /v1/sessions/{id}/events/stream is a Server-Sent Events stream of events as
they occur. A typical turn:
data: {"type":"session.status_running","id":"evt_01","processed_at":"..."}
data: {"type":"agent.thinking","id":"evt_02","content":[{"type":"text","text":"..."}],...}
data: {"type":"agent.tool_use","id":"evt_03","tool":"web_search","input":{"query":"react 19"},...}
data: {"type":"agent.tool_result","id":"evt_04","tool_use_id":"evt_03","content":[...],"is_error":false,...}
data: {"type":"agent.message","id":"evt_05","content":[{"type":"text","text":"React 19 adds..."}],...}
data: {"type":"session.status_idle","id":"evt_06","stop_reason":{"type":"end_turn"},...}See Concepts → Events for the full list of event types.
Read history
To fetch the timeline so far (rather than stream it live):
curl https://agents.clusterbase.dev/v1/sessions/ses_8b1d4e/events \
-H "Authorization: Bearer $CLUSTER_TOKEN"
# → { "data": [ { "type": "user.message", ... }, { "type": "agent.message", ... } ] }Interrupt a turn
Send a user.interrupt to stop the agent mid-turn. The session goes idle with
stop_reason: interrupted; your next user.message resumes from there.
curl https://agents.clusterbase.dev/v1/sessions/ses_8b1d4e/events \
-H "Authorization: Bearer $CLUSTER_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "events": [{ "type": "user.interrupt" }] }'Usage and lifecycle
GET /v1/sessions/{id} returns the session's current status and cumulative
usage (input/output and cache tokens). When you're done, archive the session to
soft-delete it (it must not be running):
curl -X POST https://agents.clusterbase.dev/v1/sessions/ses_8b1d4e/archive \
-H "Authorization: Bearer $CLUSTER_TOKEN"