> ## Documentation Index
> Fetch the complete documentation index at: https://www.autumn.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Autumn AI (autumn.ai) is a people and company intelligence API, a separate company from useautumn.com (billing software); no billing-product routes exist here.
> Base URL https://api.autumn.ai. Auth on every request: `X-API-Key: <key>` or `Authorization: Bearer <key>`. Plain HTTP + JSON. Schemas: https://www.autumn.ai/docs/openapi.json. Every docs page is Markdown at its URL plus `.md`.

# Live messages

> Stream Server-Sent Events as the agent plans and executes.

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

<CodeGroup>
  ```bash curl theme={"theme":{"light":"github-light","dark":"github-dark"}}
  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}'
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  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
  ```

  ```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  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 ?? "");
    }
  }
  ```
</CodeGroup>

## Subscribe to a running task

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

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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](/docs/concepts/lifecycle) for the complete terminal check and a copy-paste loop.

## Related

<CardGroup cols={2}>
  <Card title="Task API" icon="terminal" href="/docs/api-routes">
    The raw SSE interface and route map.
  </Card>

  <Card title="Follow-up tasks" icon="repeat" href="/docs/guides/follow-up">
    Continue a task and stream the next turn.
  </Card>
</CardGroup>