Streaming events (SSE)

With stream=true, the run responds with a stream of events as it executes. Requests are sent with POST: read the stream with fetch, not with EventSource.

Headers and format

  • Headers: content-type: text/event-stream, cache-control: no-cache, x-run-id: r_….
  • Each event: an event: <type> line, then a data: <JSON> line.
  • A : ping line arrives roughly every 15 s: ignore it.
  • run.completed can exceed 256 KiB: do not limit the size of the read buffer.

Envelope

Each event contains run_id, seq (increasing, no gaps), t_ms, type and scope.

scopeMeaning
{"level":"run"}The whole run
{"level":"page","page":1}A page
{"level":"region","page":1,"region_id":"p1r2"}A region

Event types

typeFieldsWhen
run.startedkind, pipeline_hash, pages or duration_sStart of the run
node.startednode_id, node_typeA block starts
node.completednode_id, node_type, duration_ms, outputA block ends
node.failednode_id, node_type, errorFailure of a block (followed by run.failed)
edge.takenfrom, port, toThe data follows a link
run.completedresult, executed, trace_summaryLast event on success
run.failederror, node_id (optional)Final failure
run.cancelled—Cancellation

Content of output (node.completed)

Blockoutput
layout{"model_slug", "model_version", "regions": [{"region_id", "label", "bbox_xyxy", "writing_type"}]}
condition{"test": "table", "answer": true, "port": "yes"}
confidence{"score": 0.87, "threshold": 0.80, "port": "high", "source_node_id": "n4"}; if score is null, reason is empty_text or skipped
model_*{"status": "executed|skipped", "model_slug", "confidence", "bands"}
diarization{"speakers": 2, "turns": 14}
transcription{"confidence": 0.91}

Stream example

text
event: run.started
data: {"run_id":"r_47e35f3501c95a06","seq":1,"t_ms":0,"type":"run.started","scope":{"level":"run"},"kind":"ocr","pipeline_hash":"96c6be3b…","pages":1}

event: node.started
data: {"run_id":"r_47e35f3501c95a06","seq":2,"t_ms":4,"type":"node.started","scope":{"level":"page","page":1},"node_id":"n1","node_type":"layout"}

event: edge.taken
data: {"run_id":"r_47e35f3501c95a06","seq":9,"t_ms":812,"type":"edge.taken","scope":{"level":"region","page":1,"region_id":"p1r1"},"from":"n2","port":"yes","to":"n3"}

event: run.completed
data: {"run_id":"r_47e35f3501c95a06","seq":40,"t_ms":3150,"type":"run.completed","scope":{"level":"run"},"result":{…},"executed":{…},"trace_summary":{…}}