Subscribe to a session's real-time event stream over Server-Sent Events to receive turns, items, text deltas, and status changes.
Endpoint
GET /agents/sessions/{session_id}/events
Returns 200 text/event-stream on success. A subscription does not create a turn or start a model.
Establish and confirm the SSE connection before you POST events.
Path parameterssession_idstring (required)Session ID, for example sess_xxxQuery parametersAcceptstring (required)Request header, set to text/event-streamOpenAI-Beta string (required)Compatible clients can send agents=v1 | Request example |
Response fieldsAfter the connection is established, the stream starts with the comment line: connected. It is not a JSON event.type stringEvent typeevent_id stringEvent identitysession_id stringSession identityturn_id string / nullPresent when the event relates to a turnEvery event contains these common fields: | Response example |
Common events
Events are grouped by object. Expand a group to see the event names and payload.
Session events
Session events
| Event | Meaning |
|---|---|
agent.session.created | Session created; session is the full snapshot |
agent.session.in_progress | Session is running |
agent.session.idle | Session is idle |
agent.session.failed | Session failed |
agent.session.requires_action | Session requires client action; session is the full snapshot |
session snapshot.Environment events
Environment events
| Event | Meaning |
|---|---|
agent.session.environment.ready / failed | Environment status change; environment is a safe status summary |
environment status summary.Turn events
Turn events
| Event | Meaning |
|---|---|
agent.session.turn.created | Turn created; turn.status can be queued |
agent.session.turn.in_progress | Turn is running |
agent.session.turn.completed | Turn completed |
agent.session.turn.failed | Turn failed |
agent.session.turn.cancelled | Turn cancelled |
turn object. In turn.created, turn.status can be queued; persisted turns start at in_progress. turn.completed can include usage.Item events
Item events
| Event | Meaning |
|---|---|
agent.session.turn.item.added | Item added |
agent.session.turn.item.done | Item completed |
item and output_index. item.added can be an in-progress item; item.done is the completed item.Content part events
Content part events
| Event | Meaning |
|---|---|
agent.session.turn.content_part.added | Content part started |
agent.session.turn.content_part.done | Content part completed |
item_id, output_index, content_index, and part.Text events
Text events
| Event | Meaning |
|---|---|
agent.session.turn.output_text.delta | Output text delta |
agent.session.turn.output_text.done | Output text completed |
delta; a done event carries the full text.Reasoning summary events
Reasoning summary events
| Event | Meaning |
|---|---|
agent.session.turn.reasoning_summary_part.added / done | Reasoning summary part started or completed |
agent.session.turn.reasoning_summary_text.delta | Reasoning summary delta |
agent.session.turn.reasoning_summary_text.done | Reasoning summary completed |
summary_index to locate a part; part is the summary fragment.Reconnect
SSE does not replay deltas missed during a disconnect. After reconnecting, retrieve the session, turns, and items to recover persisted results. Do not rely on Last-Event-ID for recovery. A GET subscription does not end automatically when the session becomes idle or a single turn reaches a terminal state. [DONE] is not a success criterion.
Error codes
| HTTP status | Error type / code | Solution |
|---|---|---|
404 | not_found_error / not_found_error | Use a session ID that exists and has not been deleted in the current workspace |
502 | server_error / agents_api_upstream_unavailable | Reconnect the SSE stream. If it keeps failing, submit a ticket with x-request-id |