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 adata: <JSON>line. - A
: pingline arrives roughly every 15 s: ignore it. run.completedcan 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.
| scope | Meaning |
|---|---|
{"level":"run"} | The whole run |
{"level":"page","page":1} | A page |
{"level":"region","page":1,"region_id":"p1r2"} | A region |
Event types
| type | Fields | When |
|---|---|---|
run.started | kind, pipeline_hash, pages or duration_s | Start of the run |
node.started | node_id, node_type | A block starts |
node.completed | node_id, node_type, duration_ms, output | A block ends |
node.failed | node_id, node_type, error | Failure of a block (followed by run.failed) |
edge.taken | from, port, to | The data follows a link |
run.completed | result, executed, trace_summary | Last event on success |
run.failed | error, node_id (optional) | Final failure |
run.cancelled | — | Cancellation |
Content of output (node.completed)
| Block | output |
|---|---|
| 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":{…}}