Stream session events

GET 
/v1/sessions/:session_id/events

Follows the session as server-sent events. Every frame carries its task_id. A task sends task.started; text.delta frames with its reply text while it is written; task.progress for each step under way (a category — search, image, video, music, memory, analysis, other — and a short text); media.updated when an image, video, audio or file it produces changes status (running, completed, failed, canceled; a completed one carries an attachment whose link expires, a failed one an error); in an a2ui session, ui.updated with its whole UI data whenever that changes; suggestions with up to 3 messages the user might send next; then one task.completed, task.stopped or task.failed frame ends it, whose text is the whole reply. A generated asset may still be reported after its task ended. Every frame has its own id. To follow a task you started, send the last_event_id its request returned as Last-Event-ID: the stream sends the task from its first frame (0 sends the session from its start). Without Last-Event-ID the stream starts from now — earlier replies are read from the message list. A connection lasts at most 10 minutes; reconnect with Last-Event-ID set to the last frame's id to continue right after it. While there is nothing to send, a : ping comment comes every 15 seconds: after 45 seconds with nothing at all, treat the connection as dropped and reconnect. A user keeps at most 16 streams open at once, at most 4 on one session — opening another ends the oldest, on that session first, otherwise the user's oldest. A new stream is refused only while every stream the user holds was opened in the last 10 seconds.

Request

Responses

200

Server-sent events. In an a2ui session the end frame of a completed or stopped task also carries the UI data (ui).

401

Authentication failed: the credential is missing, malformed, expired, or revoked.

• invalid_token — The access token is invalid.
• project_disabled — This project is not active.
• token_expired — The access token has expired.
• user_disabled — This user is not active.

404

The requested resource does not exist, or is not visible to the caller.

• session_not_found — Session not found

422

A request value failed validation; the details array names each offending field.

• validation_failed — The request payload failed validation.

429

Either too many requests (a Retry-After header says when to retry) or the billing account is out of credits (no Retry-After — top up to continue); the code field tells the two apart.

• rate_limited — Too many event streams opened at once for this user. Retry in a few seconds.

500

An unexpected server-side error occurred.

• internal — An unexpected error occurred.

503

The service is temporarily unavailable; retry after a short delay.

• service_unavailable — Live updates are at capacity right now. Please retry shortly.