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

Every plan is credit-based. run_page_audit charges 100 credits per audit on Growth, Pro and Agency, debited from the workspace's monthly credit pool (Growth 1,500, Pro 3,000, Agency 5,000 credits per month). Beyond the included pool, overage is billed at 0.02 € per credit, capped by the workspace's configurable monthly overage cap.

Eligibility is checked before the audit is queued. If the workspace is out of credits or capped by its overage limit, the tool returns a structured quota_exceeded error (reason: "insufficient_credits") 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."
}

Every plan returns the same shape: mode: "credits" with creditsCharged and remainingCredits.

Error — quota exceeded

{
  "success": false,
  "ok": false,
  "error": "quota_exceeded",
  "plan": "GROWTH",
  "reason": "insufficient_credits",
  "creditsRequired": 100,
  "remainingCredits": 40,
  "upgradeUrl": "/billing",
  "message": "Workspace does not have enough credits to run another page audit. Raise the monthly overage cap or wait for the next billing period."
}

reason is always insufficient_credits: the workspace is out of credits or capped by its monthly overage cap. Raise monthlyOverageCapEuros or wait for the next billing period.

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. Call list_page_audits first and skip URLs that already have a recent COMPLETED audit.
• 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 every plan, creditsCharged and remainingCredits give the agent everything to render a "100 credits used, 4,900 remaining" line.

Related tools

• get_page_audit — poll the result.
• list_page_audits — see what's already done.