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

# Async model

> How Folio processes documents asynchronously, and the three ways to consume results.

Every document submitted to `POST /v1/documents` is processed asynchronously. The API returns `202 Accepted` immediately with a document object; the actual extraction happens in the background. This guide explains the status lifecycle and the three consumption modes.

## Status lifecycle

A document moves through the following states:

| Status                | Meaning                                                          |
| --------------------- | ---------------------------------------------------------------- |
| `queued`              | Accepted and awaiting processing.                                |
| `processing`          | Folio is extracting data from your document.                     |
| `completed`           | Extraction finished; all fields passed the confidence threshold. |
| `partially_completed` | Extraction finished, but one or more fields need human review.   |
| `failed`              | Processing could not be completed.                               |
| `deleted`             | The document was deleted via `DELETE /v1/documents/{id}`.        |

Terminal states are `completed`, `partially_completed`, `failed`, and `deleted`. Once a document reaches a terminal state it does not change again.

## Consumption modes

### 1. Webhook push (recommended for production)

Register a URL once; Folio calls it whenever a document reaches a terminal state.

```bash theme={null}
curl -X POST https://api.glialhealth.com/v1/webhook-endpoints \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{"url": "https://yourapp.example.com/folio-webhook"}'
```

Your server receives a `POST` with the event payload. No polling required. See [Webhooks](/guides/webhooks) for signature verification and event types.

**Best for:** production integrations, high volume, latency-sensitive pipelines.

### 2. Long-poll (`?wait=<seconds>`)

Pass `?wait=<seconds>` on `GET /v1/documents/{id}`. The server holds the HTTP connection open until the document leaves `queued`/`processing`, or the timeout expires (whichever comes first). The response is the updated document object.

```bash theme={null}
curl "https://api.glialhealth.com/v1/documents/doc_01j9xkqz3b0000000000000000?wait=30" \
  -H "Authorization: Bearer sk_test_..."
```

If the document finishes within the window you get the terminal status in one round-trip. If the timeout fires before processing completes, the response returns the current (non-terminal) status — loop and call again.

<Note>
  `wait=0` (the default) is an immediate poll with no hold: useful for checking status without blocking.
</Note>

**Best for:** scripts, CLIs, short-lived jobs where a persistent webhook listener is impractical.

### 3. Fetch result directly

Once you know (via webhook or poll) that the document is in a terminal state, fetch the full extraction result:

```bash theme={null}
curl https://api.glialhealth.com/v1/documents/doc_01j9xkqz3b0000000000000000/result \
  -H "Authorization: Bearer sk_test_..."
```

A `409` means the document is not yet in a terminal state. A `200` returns the full result object including `extract`, `tables`, `review_status`, `flags`, and provenance fields.

**Best for:** fetching the structured payload after any notification method has confirmed completion.

## Choosing a mode

| Scenario                                | Recommended mode                   |
| --------------------------------------- | ---------------------------------- |
| Production server-to-server integration | Webhook push                       |
| CLI or notebook — fire and wait         | Long-poll (`?wait=30`)             |
| Check status from a cron job            | Poll (`?wait=0`) then fetch result |
| Re-process or debug a past document     | Fetch result directly by ID        |

## Listing documents

You can list all documents for your organisation using `GET /v1/documents`. Supports cursor-based pagination via `limit` and `starting_after`, and a `status` filter:

```bash theme={null}
curl "https://api.glialhealth.com/v1/documents?status=partially_completed&limit=50" \
  -H "Authorization: Bearer sk_test_..."
```