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

# Ingestion status lifecycle

> The states an ingestion moves through and the transitions between them

Every ingestion reports a `status` that reflects where the document is in its lifecycle. The status starts at `CREATED` when you start an ingestion and ends at `PROCESSED` when the pipeline finishes. Cancellation and retries move it through a few intermediate states along the way.

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

## State diagram

```mermaid theme={null}
stateDiagram-v2
    [*] --> CREATED
    CREATED --> DOWNLOADING: download
    CREATED --> PENDING: enqueue
    DOWNLOADING --> PENDING: enqueue
    PENDING --> PROCESSING: process
    PROCESSING --> PROCESSED: complete
    PROCESSING --> FAILED: fail
    PROCESSING --> CANCELLING: cancel
    PROCESSED --> RETRYING: retry
    FAILED --> RETRYING: retry
    RETRYING --> PROCESSING: process
    CANCELLING --> CANCELLED: confirm_cancel
    CANCELLING --> FAILED: fail
    CANCELLED --> RETRYING: retry
```

## States

| Status        | Meaning                                                            |
| ------------- | ------------------------------------------------------------------ |
| `CREATED`     | The ingestion was accepted and is waiting to start.                |
| `DOWNLOADING` | The source file is being fetched from its URL.                     |
| `PENDING`     | The document is queued and waiting for a worker.                   |
| `PROCESSING`  | The pipeline is running `convert → split → shape → extract`.       |
| `PROCESSED`   | The pipeline finished and the result is loaded into the workspace. |
| `RETRYING`    | A failed or interrupted run is being restarted.                    |
| `CANCELLING`  | A cancellation request is being applied.                           |
| `CANCELLED`   | The ingestion stopped before completing. You can retry from here.  |
| `FAILED`      | A step could not complete. 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 an ingestion can only move between valid states.

* A `cancel` request on a running ingestion moves it through `CANCELLING` to `CANCELLED`.
* A `retry` from `FAILED`, `PROCESSED`, or `CANCELLED` moves the ingestion through `RETRYING` back into `PROCESSING`.

For the API calls that trigger cancellation and retries, see [Handle interruptions](/cookbooks/ingestion#handle-interruptions).