Stream a task into your UI

A task that runs for minutes needs to show the user something better than a spinner. The public API stream sends quiet status changes, so your UI can show progress, questions, errors, and newly saved rows without receiving every tool call or text delta.

1. Keep the API key on your server

Every stream route requires your API key, so the browser must never connect to api.autumn.ai directly. Start the task server-side, then either proxy the SSE stream through your backend or forward its events over your own channel.

// server: start the task, return only the task_id to the browser
const { task_id } = await fetch("https://api.autumn.ai/task", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.AUTUMN_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ prompt, clarify: false }),
}).then((r) => r.json());

GET /task/{task_id}/stream sends the current status first, then one event per status version change. A user who opens the page mid-run still sees the latest state:

// server: proxy the task's event stream
const upstream = await fetch(`https://api.autumn.ai/task/${taskId}/stream`, {
  headers: { "X-API-Key": process.env.AUTUMN_API_KEY },
});
// pipe upstream.body to the client response with SSE headers

This split (one process starts, another watches) keeps the API key on your server. See Live messages for reconnect behavior and event parsing.

3. Map events to UI states

Each event carries the status fields, a printable summary, and an event name:

Event	UI
`status`	Refresh the visible lifecycle state and summary.
`message`	Show the latest public-facing task message.
`rows`	Refresh the row count or table.
`error`	Show the failure details from `error`.
`done`	Close the feed and inspect `state` and `done`.

The SSE id is the status version; pass it as Last-Event-ID on reconnect. A repeated version does not emit the same status again. The default stream is quiet; ?verbose=1 selects the legacy raw feed. The dashboard stream is unaffected.

4. When the turn is done, fetch the rows

When done is true, inspect state: for completed, refresh the table from GET /task/{task_id}/output, flattening cells for display and keeping _sources so each value can link to where it came from. For input-required, show message and offer an answer action; a done turn does not necessarily end the task conversation. Outputs and sources covers the cell shape.

5. Wire the follow-up box to continue

The natural next interaction is the user asking for changes. Send that through POST /task/{task_id}/continue; if a turn is running, the follow-up queues and the API returns 202. Keep the box available while the task runs, and show queue_position from the response. Decision: if your UI only needs a progress bar and a finished table, skip the stream entirely and call GET /task/{task_id}?wait=50 until done is true. Streaming earns its complexity when users watch.

Live messages

The SSE mechanics: routes, parsing, and event names.

Build a reviewed list

Put a human reviewer behind this UI.

Start here

Pipelines

Production wiring

Agents

Stream a task into your UI

1. Keep the API key on your server

3. Map events to UI states

4. When the turn is done, fetch the rows

5. Wire the follow-up box to continue

Live messages

Build a reviewed list

​1. Keep the API key on your server

​2. Subscribe on the server, relay to the client

​3. Map events to UI states

​4. When the turn is done, fetch the rows

​5. Wire the follow-up box to continue

​Related

Live messages

Build a reviewed list

1. Keep the API key on your server

2. Subscribe on the server, relay to the client

3. Map events to UI states

4. When the turn is done, fetch the rows

5. Wire the follow-up box to continue

Related