Statuses and polling¶
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:
{"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 theRetry-Afterheader.url- poll this URL again (your request's path with the export parameterslanganddetail).retry_after- older name ofretry_after_s, kept for existing clients.
A browser (Accept: text/html) gets a page that refreshes itself instead of JSON.