# Statuses and polling

Source: https://docs.askaniela.com/reference/statuses/

Long-running work (jobs, site audits, audit exports) uses the same machine-readable statuses and the same
way of telling you when to ask again.

## Job and audit status

`status` on `POST /v1/jobs` (202), `GET /v1/jobs/{id}`, `POST /v1/audits/site` (202), `GET /v1/audits/{id}`
(top level and `progress.status`) and `audit.status` in `export.json` is one enum, `JobStatus`:

| Value | Meaning |
|---|---|
| `queued` | Accepted, waiting for a worker. |
| `running` | Pages are being checked. |
| `pausing` | Pause requested; pages in flight finish, new ones do not start. |
| `paused` | Paused; resume to continue. |
| `cancelling` | Stop requested; pages in flight are settled. |
| `cancelled` | Stopped; checked pages stay, unchecked pages are refunded. |
| `done` | Every page processed (some may have failed, see `failed`). |
| `failed` | Every page failed or the job could not run. |

Final statuses: `done`, `failed`, `cancelled`. While a job or audit is not final (`queued`, `running`, `pausing`,
`paused`, `cancelling`), `GET` sends a `Retry-After` header (seconds, 15-300, from the remaining-time estimate).
A `paused` job or audit does not move on by itself - it continues only after you resume it. The `202` that accepts a job or
an audit sends `Retry-After: 15` for the first poll.

## Search intent

`POST /v1/intent` answers `200` when the phrase is already finished and `202` while it is `queued` or `running`
(body: the intent report with its `status`, values `queued`, `running`, `done`, `failed` - the same words as
`JobStatus`), with `Retry-After: 5`. Poll `GET /v1/intent/{id}`. `POST /v1/intent/batch` (and `/csv`) answers `202`
with `Retry-After: 5`.

## Exports prepared in the background

`GET /v1/audits/{id}/export.json`, `export.zip` and `export.pdf` are built by a worker and cached. Export
status is a separate enum, `ExportStatus`: `ready` (you get the file), `pending` (`202`) or `failed`
(`503`, `export_unavailable` / `pdf_unavailable`).

The `202` body (`Pending`) is the same for every export:

```json
{"status": "pending", "retry_after_s": 7, "url": "/v1/audits/aud_.../export.json?lang=en", "retry_after": 7}
```

- `retry_after_s` - seconds to wait; the same value is in the `Retry-After` header.
- `url` - poll this URL again (your request's path with the export parameters `lang` and `detail`).
- `retry_after` - older name of `retry_after_s`, kept for existing clients.

A browser (`Accept: text/html`) gets a page that refreshes itself instead of JSON.