Skip to navigation

Streaming

Follow a job with server-sent events. Resume after a cut connection.

View as Markdown

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.

curl -N -X POST "https://$CRK_SLUG.cloudraker.run/v2/parse" \
-H "Authorization: Bearer $CRK_API_KEY" \
-H "Accept: text/event-stream" \
-H "Content-Type: application/json" \
-d '{ "file": { "url": "https://www.irs.gov/pub/irs-pdf/fw9.pdf" } }'

-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:

id: 1
event: job.progress
data: {"seq":1,"type":"job.progress","created_at":"2026-11-07T14:02:12Z","job_id":"job_01JC9M…","data":{"step":1,"total":6,"message":"Parsing page 1"}}
id: 2
event: job.succeeded
data: {"seq":2,"type":"job.succeeded","created_at":"2026-11-07T14:02:13Z","job_id":"job_01JC9M…","data":{"job":{"object":"job","id":"job_01JC9M…","status":"succeeded"}}}
EventTerminaldata
job.progressNo{step?, total?, message?}: the progress of the job.
job.needs_inputNo{job}: the job as it was at the event. The stream continues.
job.succeededYes{job}: the final job, with its output.
job.failedYes{job}: the final job, with its error.
job.cancelledYes{job}: the final job.
job.expiredYes{job}: the final job.

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:

curl -N "https://$CRK_SLUG.cloudraker.run/v2/jobs/job_01JC9M…" \
-H "Authorization: Bearer $CRK_API_KEY" \
-H "Accept: text/event-stream" \
-H "Last-Event-ID: 2"

The API sends the events with a higher seq, then the live events.

ResultAnswer
The job ended, and the client has every event204
Last-Event-ID is not a whole number400 invalid_request
The credential cannot read the job404 job_not_found
Too many open streams on this tenant429 concurrency_limited

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.