run_page_audit

run_page_audit queues a Page Audit on a URL and returns an auditId immediately. The audit runs asynchronously (typically 30–90 seconds) and goes through PENDING → GENERATING → COMPLETED. Poll get_page_audit to fetch the modifications when ready.

Requires member role minimum. customer role is rejected.

Billing

Costs depend on the workspace plan:

Plan	Cost	Limit
Starter	n/a	Page audits not included; tool returns quota_exceeded:disabled.
Growth	Free	4 audits per billing month.
Pro	Free	10 audits per billing month.
Agency	100 credits	Unlimited; capped by monthlyOverageCapEuros if set.

Eligibility is checked before the audit is queued. If the workspace cannot run another audit, the tool returns a structured quota_exceeded error and no work is started.

In development (NODE_ENV=development), the eligibility check and credit charge are bypassed.

Async lifecycle

1. run_page_audit returns { success: true, auditId, status: "PENDING" }.
2. Poll get_page_audit with the auditId. While PENDING/GENERATING, the response is minimal.
3. On COMPLETED, get_page_audit returns the full summary and modifications.
4. On FAILED, get_page_audit returns an errorMessage.

Input

Field	Type	Description
projectId	string (CUID)	Project scope.
pageUrl	string (URL)	Full URL of the page to audit. Must be https:// and publicly accessible.

Response

Success — audit queued

{
  "success": true,
  "auditId": "clx_rep_42",
  "status": "PENDING",
  "plan": "AGENCY",
  "mode": "credits",
  "creditsCharged": 100,
  "remainingCredits": 4900,
  "message": "Audit queued. Poll get_page_audit with this auditId to fetch results when status transitions to COMPLETED."
}

For Growth/Pro the response includes mode: "quota" and remainingAuditsThisMonth instead of creditsCharged/remainingCredits.

Error — quota exceeded

{
  "success": false,
  "ok": false,
  "error": "quota_exceeded",
  "plan": "GROWTH",
  "reason": "quota_reached",
  "auditsThisPeriod": 4,
  "quotaPerMonth": 4,
  "upgradeUrl": "/billing",
  "message": "Workspace cannot run another page audit right now. Inspect the `reason` and either upgrade or raise the overage cap."
}

reason is one of:

• disabled — plan does not include page audits (Starter).
• quota_reached — Growth/Pro hit the monthly cap; renews at the next billing period.
• insufficient_credits — Agency hit the overage cap; raise monthlyOverageCapEuros or wait for renewal.

Error — fetch failed

{
  "success": false,
  "ok": false,
  "error": "fetch_failed",
  "message": "Could not fetch the page. The URL may be private, redirecting, or blocking crawlers."
}

No credits are charged when the page cannot be fetched.

Tips and patterns

• Always check success first, then branch on error for the structured cases above.
• De-dup before queueing. list_missed_citations returns hasExistingAudit; only audit pages with false.
• Poll, don't block. Loop get_page_audit every 10–20 seconds. Don't tighten the loop further — the audit is bound by an LLM call, not your polling.
• Surface the cost to the user. On Agency, creditsCharged and remainingCredits give the agent everything to render a "100 credits used, 4,900 remaining" line.

Related tools

• list_missed_citations — pick the URLs most worth auditing.
• get_page_audit — poll the result.
• list_page_audits — see what's already done.