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

# Query status lifecycle

> The states a query moves through and the transitions between them

Every query reports a `status` that reflects where it is in its lifecycle. The status starts at `PENDING` when you create a query and ends at `PROCESSED` when the answer is ready. Failures and retries move it through intermediate states along the way.

Poll the [get query](/cookbooks/query#poll-for-completion) endpoint and read `status` to track progress.

## State diagram

```mermaid theme={null}
stateDiagram-v2
    [*] --> PENDING
    PENDING --> PROCESSING: process
    PROCESSING --> PROCESSED: complete
    PENDING --> FAILED: fail
    PROCESSING --> FAILED: fail
    PROCESSED --> FAILED: fail
    FAILED --> PENDING: retry
```

## States

| Status       | Meaning                                                               |
| ------------ | --------------------------------------------------------------------- |
| `PENDING`    | The query was accepted and is waiting for the workflow to start.      |
| `PROCESSING` | The workflow is actively processing the query.                        |
| `PROCESSED`  | The query finished and the answer is available in the `output` field. |
| `FAILED`     | The query could not be answered. You can retry from here.             |

## Transitions

Each arrow in the diagram is an allowed transition. Any status change that is not in the diagram is rejected, so a query can only move between valid states.

* A query moves from `PENDING` to `PROCESSING` when the workflow starts execution.
* The `complete` transition moves from `PROCESSING` to `PROCESSED` when the workflow produces an answer.
* A `fail` transition can happen from any state (workflow error or late failure).
* A `retry` from `FAILED` moves the query back to `PENDING` to restart the workflow.

For the API calls that work with queries, see [Working with queries](/cookbooks/query).