Skip to main content
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.
  • An integration webhook endpoint subscribed to site_audit.completed, or a client that can poll. See Integration webhooks.
  • Credits for the pages you audit.
All values are synthetic.

Steps

1

Read the action and its version

List actions returns each action with its version. Pick the action and note its id and version.
2

Mark the action 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.
3

Add the page to Site Diagnostics

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

Preview the audit cost

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

Start the audit

Repeat the request without dryRun and with a new Idempotency-Key.
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.
6

Wait for site_audit.completed

Your endpoint receives a signed event when every page has finished:
Deduplicate on id, then read Get a page audit with data.auditId. Without a webhook, poll that endpoint until status is COMPLETED.
7

Read the page results

Get a monitored page 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.