Start a page audit
curl --request POST \
--url https://www.qwairy.co/api/v1/brands/{brandId}/site-diagnostics/audits \
--header 'Authorization: <authorization>' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: <idempotency-key>' \
--data '
{
"pageIds": [
"<string>"
],
"all": true,
"dryRun": true
}
'import requests
url = "https://www.qwairy.co/api/v1/brands/{brandId}/site-diagnostics/audits"
payload = {
"pageIds": ["<string>"],
"all": True,
"dryRun": True
}
headers = {
"Authorization": "<authorization>",
"Idempotency-Key": "<idempotency-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
Authorization: '<authorization>',
'Idempotency-Key': '<idempotency-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({pageIds: ['<string>'], all: true, dryRun: true})
};
fetch('https://www.qwairy.co/api/v1/brands/{brandId}/site-diagnostics/audits', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));Site diagnostics
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.
POST
https://www.qwairy.co
/
api
/
v1
/
brands
/
{brandId}
/
site-diagnostics
/
audits
Start a page audit
curl --request POST \
--url https://www.qwairy.co/api/v1/brands/{brandId}/site-diagnostics/audits \
--header 'Authorization: <authorization>' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: <idempotency-key>' \
--data '
{
"pageIds": [
"<string>"
],
"all": true,
"dryRun": true
}
'import requests
url = "https://www.qwairy.co/api/v1/brands/{brandId}/site-diagnostics/audits"
payload = {
"pageIds": ["<string>"],
"all": True,
"dryRun": True
}
headers = {
"Authorization": "<authorization>",
"Idempotency-Key": "<idempotency-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
Authorization: '<authorization>',
'Idempotency-Key': '<idempotency-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({pageIds: ['<string>'], all: true, dryRun: true})
};
fetch('https://www.qwairy.co/api/v1/brands/{brandId}/site-diagnostics/audits', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));Audits up to 50 monitored pages, or every monitored page with
Send either
See Error codes for authentication, plan, idempotency and server errors. A token without write access returns
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.
Unique key for this operation, at most 255 characters. Completed responses replay for 24 hours.
Audit every monitored page, up to 10,000. Above this limit, use several requests
with
pageIds. Cannot be combined with pageIds.pageIds or all.
Return the pages and
creditsReserved without starting the audit or
reserving credits. The response is 200 with status: "PREVIEW" and id: null.Response
Returns202 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
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"]}'
{
"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 |
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.
