Skip to main content
POST
Start a page audit
Audits up to 50 monitored pages, or every monitored page with all set to true. The request returns 202 with the audit and a Location header. Poll Get a page audit, or subscribe an integration webhook to site_audit.completed. Pages that are already being audited are reported as SKIPPED in the audit. Each audited page uses 5 credits, as in the dashboard. The balance is checked before acceptance; each page reserves its credits when its worker starts and spends them when its results are saved. creditsReserved is the audit’s credit budget, not an immediate hold or a bill. Send dryRun: true to preview it without starting anything. A 202 means the request is durably accepted, not that every page has started. The request itself queues an audit of 100 pages to audit or fewer. A larger audit is returned without waiting: its pages are QUEUED, and a background job that runs every five minutes queues them, possibly before the response arrives. Queueing is retried within 24 hours of acceptance, with at most 12 attempts including the first; an attempt interrupted before it records its outcome can run again within that window. Pages the queue has not taken by then are FAILED. Every attempt reuses the same keys, so a page is never queued or debited twice. Poll the same audit instead of creating a new one. When the balance is already insufficient, the request returns 409 INSUFFICIENT_CREDITS and starts nothing. If the balance is spent after acceptance, the response depends on how far the audit got. When no page started and the request queued the audit itself (100 pages to audit or fewer), the same 409 includes details.auditId: the audit is retained with its pages FAILED and can be read. In every other case, including an audit queued by the background job, the response stays 202: the pages that could not start are FAILED, the pages already started keep running, and the audit shows the outcome of each page. Requires an active Business, Agency Business or Enterprise plan, and an API token with write access enabled by an Owner or Manager. See Writing data for activation, idempotency, conditional requests and error handling.
string
required
Bearer token for your team.
string
required
Unique key for this operation, at most 255 characters. Completed responses replay for 24 hours.
string
required
Workspace identifier. The workspace must belong to the token’s team.
string[]
Between 1 and 50 monitored page identifiers. Cannot be combined with all.
boolean
Audit every monitored page, up to 10,000. Above this limit, use several requests with pageIds. Cannot be combined with pageIds.
Send either pageIds or all.
boolean
default:"false"
Return the pages and creditsReserved without starting the audit or reserving credits. The response is 200 with status: "PREVIEW" and id: null.

Response

Returns 202 with an audit object, or 200 with a PREVIEW audit when dryRun is true. creditsReserved is 5 credits per page to audit; it can decrease if dispatch refuses pages. For a dry run it is the estimated budget. See Get a page audit for the fields.

Synthetic request and response

Errors

See Error codes for authentication, plan, idempotency and server errors. A token without write access returns 403 API_KEY_READ_ONLY. On 429, honor Retry-After. If the write limiter is unavailable or writes are suspended, the request returns 503 SERVICE_UNAVAILABLE and nothing changes.