Live messages

Stream messages as the agent works: planning, tool calls, and progress. Autumn emits Server-Sent Events on the /stream routes, with the same event names the dashboard uses. Two ways in:

Route	Use
`POST /task/stream`	Start a task from a prompt and stream the turn it kicks off.
`GET /task/{task_id}/stream`	Subscribe to an existing task. Recent events replay if a turn is already active.

Start and stream

curl -N -X POST "https://api.autumn.ai/task/stream" \
  -H "X-API-Key: $AUTUMN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Find the top story on Hacker News", "clarify": false}'

import os, json, requests

with requests.post(
    "https://api.autumn.ai/task/stream",
    headers={"X-API-Key": os.environ["AUTUMN_API_KEY"]},
    json={"prompt": "Find the top story on Hacker News", "clarify": False},
    stream=True,
) as r:
    event = None
    for line in r.iter_lines(decode_unicode=True):
        if not line:
            continue
        if line.startswith("event:"):
            event = line[6:].strip()
        elif line.startswith("data:"):
            data = json.loads(line[5:].strip())
            print(f"[{event}] {data.get('summary', '')}")
            if event == "done":
                break

const res = await fetch("https://api.autumn.ai/task/stream", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.AUTUMN_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ prompt: "Find the top story on Hacker News", clarify: false }),
});

const reader = res.body.pipeThrough(new TextDecoderStream()).getReader();
let buffer = "";
while (true) {
  const { value, done } = await reader.read();
  if (done) break;
  buffer += value;
  const chunks = buffer.split("\n\n");
  buffer = chunks.pop() ?? "";
  for (const chunk of chunks) {
    const event = chunk.match(/^event:\s*(.*)$/m)?.[1];
    const data = chunk.match(/^data:\s*(.*)$/m)?.[1];
    if (data) console.log(`[${event}]`, JSON.parse(data).summary ?? "");
  }
}

Already have a task_id? Attach to it. This is the route to use when one process starts the task and another watches it.

curl -N "https://api.autumn.ai/task/8fab6f34/stream" \
  -H "X-API-Key: $AUTUMN_API_KEY"

GET /task/{task_id}/stream only streams events for that task_id. When the turn emits done, the stream can close. Reconnect later only if you need the next active turn.

Event names

Event	Meaning
`tool_start`	A task operation or tool call began.
`tool_result`	A task operation or tool call produced a result.
`text_delta`	Assistant or status text from the sandboxed agent.
`beanstalk_error`	A user-visible task error.
`done`	The current turn finished.

Each message carries a type, a summary, and data. Treat done as end-of-turn, not end-of-task; a task can run more turns if you continue it.

Streaming the other routes

Every route that advances a task has a streaming twin. Same body, SSE response:

Blocking	Streaming
`POST /task`	`POST /task/stream`
`POST /task/start`	`POST /task/start/stream`
`POST /task/{task_id}/continue`	`POST /task/{task_id}/continue/stream`
`POST /task/{task_id}/execute`	`POST /task/{task_id}/execute/stream`

Polling instead of streaming

Streaming is optional. Poll GET /task/{task_id} when you only care about the result; a long-running task doesn’t need a held-open connection. Getting the loop’s exit condition right is subtler than it looks: a finished task returns to status: "plan", which is also its state before execution. See Task lifecycle for the complete terminal check and a copy-paste loop.

Task API

The raw SSE interface and route map.

Follow-up tasks

Continue a task and stream the next turn.

Get started

Core concepts

Guides

Best practices

Use with agents

Start and stream

Event names

Streaming the other routes

Polling instead of streaming

Task API

Follow-up tasks

​Start and stream

​Subscribe to a running task

​Event names

​Streaming the other routes

​Polling instead of streaming

​Related

Task API

Follow-up tasks

Start and stream

Subscribe to a running task

Event names

Streaming the other routes

Polling instead of streaming

Related