Skip to main content

Subscribe to event SSE

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 parameters

session_id string (required)Session ID, for example sess_xxx

Query parameters

Accept string (required)Request header, set to text/event-streamOpenAI-Beta string (required)Compatible clients can send agents=v1

Request example

curl -N "$BASE_URL/agents/sessions/sess_xxx/events" \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "OpenAI-Beta: agents=v1" \
  -H "Accept: text/event-stream"

Response fields

After 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

: connected

data: {"type":"agent.session.turn.output_text.delta","event_id":"evt_xxx","session_id":"sess_xxx","turn_id":"turn_xxx","item_id":"msg_xxx","output_index":0,"content_index":0,"delta":"hello"}

Common events

Events are grouped by object. Expand a group to see the event names and payload.
EventMeaning
agent.session.createdSession created; session is the full snapshot
agent.session.in_progressSession is running
agent.session.idleSession is idle
agent.session.failedSession failed
agent.session.requires_actionSession requires client action; session is the full snapshot
The event carries the full session snapshot.
EventMeaning
agent.session.environment.ready / failedEnvironment status change; environment is a safe status summary
The event carries a safe environment status summary.
EventMeaning
agent.session.turn.createdTurn created; turn.status can be queued
agent.session.turn.in_progressTurn is running
agent.session.turn.completedTurn completed
agent.session.turn.failedTurn failed
agent.session.turn.cancelledTurn cancelled
The event carries the full public turn object. In turn.created, turn.status can be queued; persisted turns start at in_progress. turn.completed can include usage.
EventMeaning
agent.session.turn.item.addedItem added
agent.session.turn.item.doneItem completed
The event carries item and output_index. item.added can be an in-progress item; item.done is the completed item.
EventMeaning
agent.session.turn.content_part.addedContent part started
agent.session.turn.content_part.doneContent part completed
The event carries item_id, output_index, content_index, and part.
EventMeaning
agent.session.turn.output_text.deltaOutput text delta
agent.session.turn.output_text.doneOutput text completed
A delta event carries delta; a done event carries the full text.
EventMeaning
agent.session.turn.reasoning_summary_part.added / doneReasoning summary part started or completed
agent.session.turn.reasoning_summary_text.deltaReasoning summary delta
agent.session.turn.reasoning_summary_text.doneReasoning summary completed
Use 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 statusError type / codeSolution
404not_found_error / not_found_errorUse a session ID that exists and has not been deleted in the current workspace
502server_error / agents_api_upstream_unavailableReconnect the SSE stream. If it keeps failing, submit a ticket with x-request-id
When the connection drops, the HTTP stream ends. A new subscription does not deliver events missed while offline.