Guides

Streaming a run

Render the report about a third of the way in, and let the summary type in after it.

GET/api/v1/stream?target={target}&subject={subject}API key

Run an analysis and stream its progress

The evidence is complete long before the run is. The AI summary is over half the wall time, so streaming lets the findings render as soon as they exist while the prose arrives afterwards. The work takes just as long; the finished parts stop waiting on the slow one.

The events

Server-sent events, one JSON object per data: frame:

text/event-stream

event: stage
data: {"stage":"agents","status":"running"}

event: evidence
data: {"items":[ … ]}

event: result
data: {"execution_id":"ex_…","facts":{ … }}

event: summary
data: {"summary":"…","summary_status":"generated"}

event: done
data: {"execution_id":"ex_…"}

Reading it in a browser

TypeScript

const response = await fetch(url, {
  headers: {
    accept: "text/event-stream",
    authorization: `Bearer ${key}`,
  },
});

const reader = response.body!
  .pipeThrough(new TextDecoderStream())
  .getReader();

let buffer = "";
while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  buffer += value;

  let boundary = buffer.indexOf("\n\n");
  while (boundary !== -1) {
    const frame = buffer.slice(0, boundary);
    buffer = buffer.slice(boundary + 2);
    boundary = buffer.indexOf("\n\n");
    // parse the "data:" line of `frame`
  }
}

Free-form requests use POST /api/v1/execute instead, because the router has to read the text before it knows the target.