Run a site audit
run_site_auditStarts a site audit. It crawls the site (same origin, following robots.txt), checks each page for SEO problems such as broken links, missing or duplicate titles and descriptions, redirect chains, orphan pages, canonical mistakes and pages blocked by robots.txt, and can run Lighthouse on a sample of pages. The crawl is free. Lighthouse is paid (up to 10 pages on mobile and desktop, up to 20 tests, up to $0.20) and is billed while the audit runs. The audit works in the background: poll get_audit_status, then read get_audit_issues, and get_audit_pages for Lighthouse scores. When a site rate limits the crawler it backs off and retries, and pages it still cannot read are marked blocked or rate-limited instead of being guessed at. Every audit crawls at one gentle pace, about a page a second, and crawlSpeed is accepted but ignored. The crawler slows down by itself; if the site keeps refusing, allow our crawler by name and address (the bot page lists both). The crawler calls itself VisibilityGeniesBot unless crawlerIdentity says otherwise: desktop or mobile send a browser user agent that keeps that token, while chrome_windows, firefox_windows, safari_macos, chrome_android and safari_iphone send an ordinary browser's headers without it, and none imitates a search engine. Pages are read as HTML, with no JavaScript, unless renderJavaScript is true. The project Owner may let audits of the project's own site ignore robots.txt, and those audits report a robots-txt-ignored finding. Each call may spend up to the workspace's agent spend limit ($2.00 unless changed in Settings) without asking: it holds at most its estimate plus a margin while it runs and is charged what it bought, never more. A call whose maximum is above the limit is refused before anything is bought, with its estimate and maximum: ask the user, then call again with approvedMaxCostUsd set to the amount they approved.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"projectId": "<projectId>",
"url": "<url>"
},
"name": "run_site_audit"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | Start URL to crawl. | |
| maxPages | No | Page budget for the crawl (default 50). | |
| crawlMode | No | search_engine (default) follows links outward from the start page the way a search engine discovers pages. full_inventory also seeds every sitemap URL so orphan pages show up. | search_engine |
| projectId | Yes | Required. The Visibility Genies project this call works in and is billed to. Call list_projects to find one. | |
| crawlSpeed | No | Ignored. Every audit crawls at one gentle pace, about a page a second. | |
| ignoreParams | No | Query parameters to strip before comparing URLs, so ?page=1 and ?page=2 count as one page (up to 50). | |
| disallowPaths | No | Path prefixes to leave out, such as /tag or /search (up to 50). A prefix excludes everything beneath it. | |
| runLighthouse | No | Also run Lighthouse. This is paid: up to 10 pages on mobile and desktop, up to 20 tests, up to $0.20. Defaults to false and adds several minutes. Set it only when the user wants performance detail from a lab test (LCP, CLS, Total Blocking Time), which is not real visitor data. | |
| crawlerIdentity | No | What the crawler calls itself. seogeniesbot is the default and sends the VisibilityGeniesBot user agent. desktop and mobile send a Chrome user agent that still names VisibilityGeniesBot. chrome_windows, firefox_windows, safari_macos, chrome_android and safari_iphone copy an ordinary visitor's request headers with no VisibilityGeniesBot token and never use the project's allow key. No choice pretends to be a search engine crawler, and all of them obey the robots.txt rules for VisibilityGeniesBot and for its former name, SEOGeniesBot. Browser identities only crawl the project's own site (its domain or the www form); any other start URL is refused. renderJavaScript works with chrome_windows and chrome_android, not with Firefox or Safari. When the Owner turned on the faster crawl for the project's own site, an audit of that site crawls as seogeniesbot whatever this says. | seogeniesbot |
| renderJavaScript | No | Load each page in a browser before reading it, for sites that build their pages with JavaScript. Defaults to false. It is slower, covers up to 500 pages per audit, and uses a hosted browser the platform pays for. Where it is not available the audit is refused and says why. | |
| approvedMaxCostUsd | No | The most, in USD, the user approved for this call after seeing its estimate and maximum. Only needed after a call was refused for costing more than the workspace's agent spend limit; never set it without asking the user. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| cost | No | ||
| meta | No | ||
| auditId | No | ||
| savedResultId | No |