Task lifecycle

Every task response has state and done for the lifecycle. Prefer those fields over legacy status, phase, and activity when deciding what to do next.

`state`	`done`	What to do
`submitted`	no	Wait. `queue_position` shows where a queued turn sits.
`working`	no	Wait; relay `message` as a short progress update.
`input-required`	yes	Show `message` as the agent’s question, then send the answer with `/continue`.
`completed`	yes	Read `/output`. `outcome: partial` means the task stopped short of its target.
`failed`	yes	Report `error.message`; `out_of_credits` is a hard stop: link https://platform.autumn.ai/?settings=usage.
`canceled`	yes	The turn was stopped. Rows already saved remain available from `/output`.

Rows do not wait for done. A person or company task usually saves its row well before the turn ends, while the agent verifies and writes its summary. progress.rows counts the rows saved so far, and GET /task/{task_id}/output returns them at any time, so read output as soon as progress.rows reaches what you need. done means the current turn has stopped, not necessarily that the task conversation is over. For input-required, answer the question and continue the same task_id. If follow-up messages are queued, queued_messages keeps the lifecycle active until the queue drains.

Wait for a status change

import time

def get_status(task_id):
    while True:
        r = requests.get(
            f"{AUTUMN}/task/{task_id}",
            headers=HEADERS,
            params=dict(wait=50),
        )
        if r.status_code in (429, 503):
            time.sleep(float(r.headers.get("Retry-After", 5)))
            continue
        if not 200 <= r.status_code < 300:
            raise RuntimeError(r.json().get("message") or r.text)
        return r.json()

task = get_status(task_id)
while not task["done"]:
    task = get_status(task_id)

async function getStatus(taskId) {
  while (true) {
    const r = await fetch(`${AUTUMN}/task/${taskId}?wait=50`, { headers: HEADERS });
    if (r.status === 429 || r.status === 503) {
      const seconds = Number(r.headers.get("Retry-After") || 5);
      await new Promise((resolve) => setTimeout(resolve, seconds * 1000));
      continue;
    }
    const body = await r.json();
    if (!r.ok) throw new Error(body.message || "Status request failed");
    return body;
  }
}

let task = await getStatus(taskId);
while (!task.done) {
  task = await getStatus(taskId);
}

wait is available on GET /task/{task_id} and GET /task/{task_id}/state; it is clamped to 0–50 seconds. A request returns immediately when the current status is done, otherwise it returns on the first status-version change or at the timeout. Use the returned version for change detection and SSE event IDs. See Live messages for the status stream.

Legacy fields

status, phase, and activity remain in responses for compatibility. Their values and meaning are unchanged. status: "plan" is the resting phase before and after every turn: a finished task reads status: "plan" and state: "completed" at the same time, and it does not need POST /task/{task_id}/execute. Use state and done for lifecycle decisions.

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. A stopped turn has state: "canceled"; stopping does not delete the task or its saved output.

Get started

Core concepts

Guides

Best practices

Use with agents

Wait for a status change

Legacy fields

After a task finishes

​Wait for a status change

​Legacy fields

​After a task finishes

Wait for a status change

Legacy fields

After a task finishes