Session events

Events are how you talk to a running session. You post input events to send messages, tool results, and cancellations, and you subscribe to output events to watch progress live. Events are the live view; the stored record is in items and turns. For a walkthrough, see the streaming guide. Paths are relative to /v1.

Method	Path	Behavior
`POST`	`/agents/sessions/{session_id}/events`	Submit a nonempty `events` array; successful admission returns `204 No Content`.
`GET`	`/agents/sessions/{session_id}/events`	Subscribe to session events as `text/event-stream`.
`POST`	`/agents/sessions`	Create a session with optional `input`; set `stream: true` for a creation stream instead of a JSON session response.

curl -N -H "Authorization: Bearer $API_KEY" \
  "$BASE_URL/agents/sessions/$SESSION_ID/events"

curl -X POST "$BASE_URL/agents/sessions/$SESSION_ID/events" \
  -H "Authorization: Bearer $API_KEY" -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: follow-up-1' \
  -d '{"events":[{"type":"agent.session.input.message","input":[{"role":"user","content":[{"type":"input_text","text":"Continue."}]}]}]}'

Input event types

Type	Purpose	Fields
`agent.session.input.message`	Send a user message. Starts a turn, or joins the running one.	`input`: a list of messages with `role` and `content`
`agent.session.input.tool_result`	Answer a function call	`turn_id`, `call_id`, `success`, and `output` (or `error` when `success` is false)
`agent.session.input.cancel`	Stop the running turn	none

Behavior

A submitted message can start a turn; do not infer completion from the 204. Follow status events or retrieve turns. Closing a GET subscription does not cancel the turn. For SSE reconnection, send Last-Event-ID with a previously received event ID; the stream emits id, event, and JSON data fields. Treat IDs as opaque. Invalid cursors can return 400.

Output event names

The pinned event inventory records the following output type names, not full validated event payload definitions:

Family	Types
Session lifecycle	`agent.session.created`, `agent.session.idle`, `agent.session.in_progress`, `agent.session.requires_action`, `agent.session.failed`
Environment	`agent.session.environment.pending`, `agent.session.environment.ready`, `agent.session.environment.connected`, `agent.session.environment.disconnected`, `agent.session.environment.failed`
Turn lifecycle	`agent.session.turn.created`, `agent.session.turn.in_progress`, `agent.session.turn.completed`, `agent.session.turn.failed`, `agent.session.turn.cancelled`
Turn content	`agent.session.turn.item.added`, `agent.session.turn.item.done`, `agent.session.turn.content_part.added`, `agent.session.turn.content_part.done`, `agent.session.turn.output_text.delta`, `agent.session.turn.output_text.done`
Reasoning summary	`agent.session.turn.reasoning_summary_part.added`, `agent.session.turn.reasoning_summary_part.done`, `agent.session.turn.reasoning_summary_text.delta`, `agent.session.turn.reasoning_summary_text.done`
Subagent	`agent.session.subagent.created`, `agent.session.subagent.active`, `agent.session.subagent.closed`
Other	`agent.output.command_execution_output.delta`, `error`

For text, concatenate delta from agent.session.turn.output_text.delta; use agent.session.turn.completed or failed to decide a turn’s outcome. Handle event types you do not recognize without assuming this table is exhaustive. Stream failures may arrive as error events after HTTP headers have already succeeded; see Errors.

​Input event types

​Behavior

​Output event names

Input event types

Behavior

Output event names