> ## 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`.

# Task lifecycle

> The states a task moves through, and how to tell when it has actually finished.

`GET /task/{task_id}` reports where a task is:

| Field      | Meaning                                                                                           |
| ---------- | ------------------------------------------------------------------------------------------------- |
| `status`   | `plan`, `execute`, or `deleted`. `plan` covers both "not started yet" and "finished and resting". |
| `activity` | What the task is doing right now. `idle` means no turn is in flight.                              |
| `phase`    | The phase of the current turn.                                                                    |
| `tier`     | The model tier the task started on, `ranger` or `scout`.                                          |

## Knowing when a task is done

This is the one piece of Autumn that reliably trips people up, so it is worth stating
precisely.

A finished task returns to `status: "plan"` with `activity: "idle"`. But `plan` is *also*
the state a task sits in **before** it executes. So `status` alone cannot tell you a task
is done. Read on its own, it will tell you a task that has not started yet is finished.

A task is **still working** while any of these hold:

* `phase` is `execute`
* `status` is `execute` or `running`
* `activity` is `executing`, `running`, `planning`, or `thinking`

It has **stopped** when none of those hold, or when `status`/`activity` is `deleted`, or
`error` is `out_of_credits`/`error`.

<Warning>
  Include the `deleted` and `error` cases in your poll loop. A loop that waits only for
  `status: "plan"` with `activity: "idle"` never exits on a task that was deleted or ran out
  of credits. It spins forever on a task that is never coming back.
</Warning>

## A correct poll loop

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  ACTIVE_STATUSES = {"execute", "running"}
  ACTIVE_ACTIVITIES = {"executing", "running", "planning", "thinking"}

  def is_terminal(task):
      if task.get("status") == "deleted" or task.get("activity") == "deleted":
          return True
      if task.get("error") in {"out_of_credits", "error"}:
          return True
      return not (task.get("phase") == "execute"
                  or task.get("status") in ACTIVE_STATUSES
                  or task.get("activity") in ACTIVE_ACTIVITIES)
  ```

  ```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const ACTIVE_STATUSES = new Set(["execute", "running"]);
  const ACTIVE_ACTIVITIES = new Set(["executing", "running", "planning", "thinking"]);

  const isTerminal = (t) =>
    t.status === "deleted" || t.activity === "deleted" ||
    ["out_of_credits", "error"].includes(t.error) ||
    !(t.phase === "execute" ||
      ACTIVE_STATUSES.has(t.status) ||
      ACTIVE_ACTIVITIES.has(t.activity));
  ```
</CodeGroup>

Prefer live events over polling? See [Live messages](/docs/guides/streaming).

## After a task finishes

A `task_id` stays valid once a turn ends. Read status and output any time, and use
`POST /task/{task_id}/continue` to start another turn on the same task. Stopping a running
task with `POST /task/{task_id}/stop` also returns it to `plan`.