Site audits
Crawl your own site for technical and on-page issues, with Lighthouse on a sample of pages.
An audit crawls the project's site, checks every page against 27 issue types, and runs Lighthouse on a sample. Starting a crawl costs credits scaling with page count; reading the results is free. The crawl is asynchronous and takes minutes.
run_site_audit
Start a crawl. Returns an auditId immediately. Poll get_audit_status until it reports completed, then read get_audit_issues.
| Argument | Type | Required | Default | Meaning |
|---|---|---|---|---|
projectId | string | yes | The project must have a domain, or startUrl must be given. | |
startUrl | string, up to 2,048 chars | no | https:// plus the project domain | Where to start. The crawl stays on the same origin; redirects from the start URL are followed first, so an apex that redirects to www anchors on the real origin. |
maxPages | integer, 10 to 10,000 | no | 50 | Page budget. A value above the plan's cap is trimmed to the cap rather than rejected, and the response says so. |
lighthouse | boolean | no | true | Also run Lighthouse on a sample of pages, mobile and desktop. Adds cost and time. |
Returns: auditId, the effective maxPages, and clampedByPlan when the budget was trimmed.
How the crawler behaves
- Identifies as
IndexZero-Audit/1.0. If your bot protection challenges it, pages are reported as blocked rather than broken, and the fix is to allowlist that user agent. - Reads and obeys
robots.txtfor that user agent, and seeds the crawl from the sitemaps it lists. - Stays on the start URL's origin. Private, loopback, and cloud-metadata addresses are refused, and hostnames are resolved to check they do not point at one.
- Adapts its concurrency to the site: starts at 10 parallel fetches, backs off when pages are slow, blocked, or erroring, and grows when the site is responding well.
- Reads at most 1 MiB of HTML per page with a 15-second timeout.
Lighthouse sampling
The sample is the homepage plus one representative page per URL template, up to 10 URLs, chosen from pages that returned 2xx. Each is run twice, mobile and desktop, so Lighthouse adds up to 20 paid calls. Captured per run: performance, accessibility, best-practices, and SEO scores, plus LCP, CLS, INP, and TTFB.
Phases
discovery, then crawling, then lighthouse, then finalizing, ending in completed or failed. get_audit_status reports the current phase and pages crawled so far. An audit that fails reports why; the most common cause is a site that takes too long to respond, and the suggested fix is a smaller page limit.
get_audit_status
Progress of a crawl: phase, pages crawled, issue count, and whether it finished. Free. Do not report on issues until status is completed; before that the numbers are partial.
| Argument | Type | Required | Meaning |
|---|---|---|---|
projectId | string | yes | |
auditId | string | no | Omit for the project's most recent audit. |
get_audit_issues
The issues a completed audit found, with the URL and detail for each. Free. Filter by severity to triage, critical first. Each issue type has a known fix; an agent should ask before changing a site.
| Argument | Type | Required | Default | Meaning |
|---|---|---|---|---|
projectId | string | yes | ||
auditId | string | no | latest audit | |
severity | critical, warning, or info | no | all | |
issueType | one of the issue type ids | no | all | See Audit issue types. |
limit | integer, 1 to 1,000 | no | 200 |
Returns: the issue rows and counts by severity.
get_audit_pages
The pages a crawl visited, with status code, title, word count, and H1s. Free. Use it to see what was actually reachable and to spot thin or untitled pages.
| Argument | Type | Required | Default |
|---|---|---|---|
projectId | string | yes | |
auditId | string | no | latest audit |
limit | integer, 1 to 1,000 | no | 100 |