> ## 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.

# Update an action, then audit pages

> Mark an Action Center recommendation in progress, add the page it concerns to Site Diagnostics, audit it for 5 credits and wait for site_audit.completed.

Follow a recommendation through the REST API: record that you are working on it, monitor the page it concerns, audit that page, and get notified when the audit finishes. A page audit uses 5 credits per page.

## Before you start

* A 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).
* An integration webhook endpoint subscribed to `site_audit.completed`, or a client that can poll. See [Integration webhooks](https://docs.qwairy.co/developers/integration-webhooks/overview.md).
* Credits for the pages you audit.

All values are synthetic.

## Steps

**1. Read the action and its version**

[List actions](https://docs.qwairy.co/developers/endpoints/actions/list.md) returns each action with its `version`. Pick the action and note its `id` and `version`.

**2. Mark the action in progress**

```bash theme={null}
curl -X PATCH "https://www.qwairy.co/api/v1/brands/$BRAND_ID/actions/$ACTION_ID" \
  -H "Authorization: Bearer $QWAIRY_API_TOKEN" \
  -H 'If-Match: "2"' \
  -H "Content-Type: application/json" \
  -d '{"status": "IN_PROGRESS"}'
```

A `412` means the action changed since you read it: read it again. Sending the current status changes nothing. See [Update an action status](https://docs.qwairy.co/developers/endpoints/actions/update-status.md).

**3. Add the page to Site Diagnostics**

```bash theme={null}
curl -X POST "https://www.qwairy.co/api/v1/brands/$BRAND_ID/site-diagnostics/pages" \
  -H "Authorization: Bearer $QWAIRY_API_TOKEN" \
  -H "Idempotency-Key: monitor-pricing-page" \
  -H "Content-Type: application/json" \
  -d '{"urls": ["https://acme.example/pricing"]}'
```

Check each item's `outcome`: `added`, `already_monitored`, `invalid` or `outside_domain`. Keep the `pageId`. Adding a page does not audit it. See [Add monitored pages](https://docs.qwairy.co/developers/endpoints/site-diagnostics/add-pages.md).

**4. Preview the audit cost**

Send `dryRun` first. The response is a `PREVIEW` audit with `id: null` and the credits it would use.

```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-preview" \
  -H "Content-Type: application/json" \
  -d '{"pageIds": ["'"$PAGE_ID"'"], "dryRun": true}'
```

```json theme={null}
{ "id": null, "status": "PREVIEW", "creditsReserved": 5, "counts": { "total": 1, "succeeded": 0, "failed": 0, "skipped": 0, "running": 0 } }
```

**5. Start the audit**

Repeat the request without `dryRun` and with a new `Idempotency-Key`.

```bash theme={null}
curl -i -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": ["'"$PAGE_ID"'"]}'
```

The response is `202` with a `Location` header and the audit's credit budget. The accepted audit is retained and interrupted queueing resumes automatically. An audit of more than 100 pages to audit is returned without waiting, and a background job queues its pages. A balance that is short at acceptance returns `409` `INSUFFICIENT_CREDITS` and starts nothing. A balance spent after acceptance returns the same `409` with `details.auditId` only when no page started and the request queued the audit itself; that accepted audit remains readable. Otherwise the response stays `202` and only the pages that could not start fail: keep following the same audit. Pages already being audited are reported as `SKIPPED`. See [Start a page audit](https://docs.qwairy.co/developers/endpoints/site-diagnostics/start-audit.md).

**6. Wait for site\_audit.completed**

Your endpoint receives a signed event when every page has finished:

```json theme={null}
{
  "id": "evt_7c1b0f9e-2d4a-4b8f-9e1a-5a6c7d8e9f01",
  "event": "site_audit.completed",
  "createdAt": "2026-11-02T09:14:07Z",
  "teamId": "team_synthetic_01",
  "brandId": "brand_synthetic_01",
  "data": {
    "auditId": "site_audit_synthetic_01",
    "counts": { "total": 1, "succeeded": 1, "failed": 0, "skipped": 0 },
    "createdAt": "2026-11-02T09:02:11Z",
    "completedAt": "2026-11-02T09:14:07Z"
  }
}
```

Deduplicate on `id`, then read [Get a page audit](https://docs.qwairy.co/developers/endpoints/site-diagnostics/get-audit.md) with `data.auditId`. Without a webhook, poll that endpoint until `status` is `COMPLETED`.

**7. Read the page results**

[Get a monitored page](https://docs.qwairy.co/developers/endpoints/site-diagnostics/get.md) returns its scores and open issues. Compare them with the page before the change, using the same page and time window.

## Limits

* `COMPLETED` means every page has a final result, not that all pages succeeded. When `counts` shows failed or skipped pages, read the audit to see which ones before you decide to audit them again. Later audits do not rewrite these results.
* The balance is checked when a page audit is accepted. As in the dashboard, each page reserves its 5 credits when its audit starts, and they are debited when its results are saved. Credit transfers and purchases remain dashboard actions.
* Changing an action status records your progress. It is not evidence that the page improved.

## Related

* [Action and site write tools](https://docs.qwairy.co/mcp/write/actions-and-site.md) for the MCP equivalent.
* [Integration webhook events](https://docs.qwairy.co/developers/integration-webhooks/events.md#site_audit-completed)


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