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

# Start a page audit

> Audit up to 50 monitored pages, or all of them, for 5 credits per page. Use dryRun to preview the cost, then poll the audit or use site_audit.completed.

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](https://docs.qwairy.co/developers/endpoints/site-diagnostics/get-audit.md), or subscribe an
[integration webhook](https://docs.qwairy.co/developers/integration-webhooks/overview.md) to
[`site_audit.completed`](https://docs.qwairy.co/developers/integration-webhooks/events#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](https://docs.qwairy.co/developers/writing-data.md) for activation, idempotency, conditional requests and error handling.

**Authorization** `string` *required*

Bearer token for your team.

**Idempotency-Key** `string` *required*

Unique key for this operation, at most 255 characters. Completed responses replay for 24 hours.

**brandId** `string` *required*

Workspace identifier. The workspace must belong to the token's team.

**pageIds** `string[]`

Between 1 and 50 monitored page identifiers. Cannot be combined with `all`.

**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`.

**dryRun** `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](https://docs.qwairy.co/developers/endpoints/site-diagnostics/get-audit.md) for the fields.

## Synthetic request and response

```bash theme={null}
curl -X POST "https://www.qwairy.co/api/v1/brands/$BRAND_ID/site-diagnostics/audits" \
  -H "Authorization: Bearer $QWAIRY_API_TOKEN" \
  -H "Idempotency-Key: audit-pricing-001" \
  -H "Content-Type: application/json" \
  -d '{"pageIds":["99999999-0000-4000-8000-000000000000"]}'
```

```json theme={null}
{
  "id": "aaaaaaaa-0000-4000-8000-000000000000",
  "status": "RUNNING",
  "counts": { "total": 1, "succeeded": 0, "failed": 0, "skipped": 0, "running": 1 },
  "creditsReserved": 5,
  "pages": [
    {
      "pageId": "99999999-0000-4000-8000-000000000000",
      "status": "QUEUED",
      "completedAt": null
    }
  ],
  "createdAt": "2026-10-12T09:00:00.000Z",
  "completedAt": null
}
```

## Errors

| Status | Code | Cause |
| - | - | - |
| `400` | `INVALID_REQUEST` | `pageIds` and `all` are combined, both are missing, or a value is invalid |
| `404` | `RESOURCE_NOT_FOUND` | The workspace is missing or inaccessible |
| `409` | `INSUFFICIENT_CREDITS` | The team balance cannot cover 5 credits per page |
| `409` | `CONFLICT` | The request conflicts with the current state |

See [Error codes](https://docs.qwairy.co/developers/errors.md) 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.