Streaming
Follow a job with server-sent events. Resume after a cut connection.
Send Accept: text/event-stream on POST /v2/{capability} or on GET /v2/jobs/{id}. The answer is a stream of server-sent events (SSE) for one job.
-N turns off the curl buffer. A POST stream has a Location: /v2/jobs/{id} header, so you can also read the job later.
Frames
Each event has an id, an event type and a JSON data line:
The stream ends after the terminal event. A run that fails during a POST stream gives the terminal event job.failed in the stream, not a 503.
seq is unique in the job and goes up. It can have gaps, because a new progress event can replace the one before it. For an agent job, seq is the seq of the Run event.
Heartbeats
The API writes the comment line : hb every 15 seconds. It keeps the connection open through a proxy. An SSE client ignores a comment line.
Resume a stream
A stream ends after 15 minutes, even if the job continues. A connection can also break. Resume with the last event id that you read:
The API sends the events with a higher seq, then the live events.
A Prefer: wait preference does not apply to a stream.
If the API cannot open a stream on POST /v2/{capability}, it answers with the JSON of the job, as with no stream. Check the content-type of the answer.
An open stream of a key ends when you revoke the key or it expires. The stream stops with no terminal event and no job output. A stream of a crt_ token ends when you delete its trust.