---
title: "Get task state"
method: GET
path: "/task/{task_id}/state"
tags: ["Tasks"]
---

# Get task state

`GET /task/{task_id}/state`

## Request

- Base URL: `https://api.autumn.ai`
- URL: `https://api.autumn.ai/task/{task_id}/state`
- Auth: one of:
  - API key in header `X-API-Key`
  - HTTP bearer

Task state for polling: repeat until done is true. Then reply if state is input-required, otherwise read /output. Saved rows are readable from /output earlier. Use wait=1-50 to long-poll. This is the status_url on every task.

## Path parameters

- `task_id` string, required: The task_id returned by POST /task or POST /task/start.

## Query parameters

- `wait` integer: Wait up to 50 seconds for the first status version change (values are clamped to 0-50).

## Response `200`

Task state.

- TaskState
  - `task_id` string, required
  - `exists` boolean, required
  - `state` string, nullable: Lifecycle state: submitted, working, input-required, completed, canceled or failed (A2A). Poll until done is true.
  - `done` boolean, nullable: True once the task has stopped: input-required (reply to continue; see next), completed, canceled or failed. Poll until true, then check state. Saved rows are readable from /output before this.
  - `message` string, nullable: Latest public-facing task message.
  - `progress` object, nullable: Rows saved so far (`rows`) and the optional `target`. Saved rows are readable from /output while done is false.
  - `active` boolean, required: Legacy. True while a turn is running, which can continue after rows are saved. Use done to tell when the task is finished.
  - `status` string, required: Legacy; use state and done.
  - `phase` string, required: Legacy; use state and done.
  - `activity` string, required: Legacy; use state and done.
  - `run_id` string, nullable
  - `heartbeat_at` string, nullable
  - `pending_op` string, nullable: A queued message or execute that has not started yet.
  - `pending_op_stale` boolean, nullable: True when the queued op has waited past its TTL and will not start.
  - `last_submit_error` string, nullable: Why the last queued (202) message or execute was rejected when it ran, e.g. out_of_credits. Empty when it ran.
  - `last_submit_error_at` string, nullable
  - `queue` QueueState
    - `position` integer, required: Place in line, 1 is next.
    - `eta_s` integer, required: Estimated seconds until the run starts.
  - `credits_used` integer, nullable: Credits used by this task.
  - `stage` string, nullable: Current stage while the task is active.
  - `elapsed_s` integer, nullable: Elapsed seconds in the current or most recent run.
  - `queue_position` integer, nullable: Place in line for a queued task, or null when not queued.
  - `queued_count` integer: Pending queued follow-ups.
  - `outcome` string, nullable: Normalized completed outcome.
  - `error` object, nullable: Public failure code and recovery guidance.
  - `next` object, nullable: Suggested next action and API call.
  - `version` string, nullable: Changes when public task status changes.
  - `app_url` string, nullable: Open the task in the Autumn app.

## Other responses

- `401`: `unauthorized`: Missing or invalid credentials. Send your full API key as `X-API-Key: <key>` or `Authorization: Bearer <key>`.
- `404`: `task_not_found`: No task with that task_id. Check the id, or list tasks with GET /task.
- `422`: `invalid_request`: a field failed validation. `param` names it; `detail` is the validator output.
- `503`: `auth_unavailable`: Key verification is temporarily unavailable. Wait `retry_after` seconds, then send the request again. | `service_unavailable`: Autumn is temporarily unavailable. Wait `retry_after` seconds, then send the request again.

---

[API](https://skmtc.dev/autumn-ai/apis/autumn-task-api.md) - [All operations](https://skmtc.dev/autumn-ai/apis/autumn-task-api/llms.txt) - [OpenAPI document](https://skmtc.dev/autumn-ai/apis/autumn-task-api/revisions/78fb43699783?raw)