Run a cloud audit
run_auditRun a cloud audit of a website (crawl + 300+ rule analysis + report). Only for sites the user owns or is authorized to test. Credits are spent as the audit runs (pay-as-you-go). The dry run is optional: pass confirm: true on the first call to start straight away. Without confirm, an audit whose estimate is over the org's auto-run threshold comes back as status "confirmation_required" with the estimate to show the user; one at or under the threshold just starts. That response carries "sufficient": true means the organization can pay, so show the estimate and call again with confirm: true; false means it cannot, and the response then carries the cost, the balance, the credit reset date and an upgrade_url for that organization. Relay those, and do NOT retry with confirm: true, which is refused. Pick the audit with level: quick (25 pages from the seed and sitemaps with external link checks, without the cloud checks), surface (100 pages, one per URL pattern, with the cloud checks and external link checks) or full (500 pages, every page it can reach; Pro and Team only: on the Free plan a full request crawls one page per URL pattern instead, up to the plan's page ceiling, and says so in level_notice). Without level the website's own level applies (a new website starts on surface). Every level checks external links, quick included, unless the website's external link setting or this run's external_links turns them off; each distinct external link the cloud verifies costs 1 credit (a link it cannot verify costs nothing), at most one per page of the page budget, and the estimate includes it. Use max_pages to size the crawl (max_pages: 1 audits just the entry URL, the cheapest run). Audits are asynchronous and take minutes: poll get_audit_status with the returned run_id, then fetch results with get_report. The website is registered automatically on first audit. A started run carries a schedule field describing the site's recurring audits: when state is active say so, since each of those runs costs credits, and settings_url is where the user turns them off. pending_first_audit: true means they switch on by themselves after this site's first successful audit, estimated_cost is the most they spend per run, week and month, and update_website_settings with schedule "off" turns them off.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | Website URL to audit, e.g. https://example.com (scheme optional). | |
| kind | No | Classify the site: 'owned' for something the user runs and monitors, 'prospect' for a lead or competitor audited once. Filterable in list_websites so a prospect cleanup can never sweep up a live site. Unclassified sites read as 'owned'. Ignored when ephemeral is true (an ephemeral site never joins the list). | |
| level | No | Audit level for this run: quick (25 pages, without the cloud checks), surface (100 pages with the cloud checks and external link checks) or full (500 pages). Default: the website's own level. Do not combine with coverage. | |
| scope | No | Which URLs to audit. 'discover' (the default) follows links from the pages it finds. 'sitemap' audits only the URLs the site's sitemap publishes, which is what you want when the sitemap is the list the user cares about and link discovery would spend the budget elsewhere. Overrides the website's stored setting for this run only. | |
| render | No | Render pages in a headless browser (default true). Catches JavaScript-dependent issues. | |
| confirm | No | Approve the credit spend. Set true to start immediately. Omitting it returns an estimate first for anything over the auto-run threshold, and starts the audit anyway for anything at or under it. | |
| coverage | No | Deprecated, use level. The old cloud depth: fast (10 pages), surface (50), deep (250) or full (500), each with the cloud checks, keeping the website's own overrides. | |
| ephemeral | No | One-shot check: run the audit and return the report without adding the site to the organization's website list, and without consuming a slot against the plan's website limit. Use for any 'just check this URL' audit the user is not going to monitor. The site is removed automatically once the audit finishes; get_audit_status and get_report keep working on the run_id. Ignored if the domain is already registered, in which case the audit runs against the existing tracked site (nothing is ever deleted) and the response reports ephemeral: false. | |
| max_pages | No | Cap the crawl at this many pages for this run. Overrides the coverage profile's page count, so max_pages: 1 audits just the entry URL for the cheapest possible run. A value above the plan's per-audit page ceiling is clamped to the ceiling and reported back in a notice, not rejected. | |
| max_credits | No | Spend guard: refuse to start if the upper-bound estimate exceeds this many credits. | |
| external_links | No | Check links to other sites for this run: true at any level, false to skip them (default: the website's setting). Each distinct external link the cloud verifies costs 1 credit (a link it cannot verify costs nothing), at most one per page of the run's page budget, and the estimate includes that. Skipped links are listed as not checked in the report. | |
| internal_links | No | Status-check internal link targets the crawl did not fetch (a HEAD request each, a one-byte GET only when the server refuses HEAD, following redirects that stay in scope; free; it never requests links that look like actions or carry a token). Default: the website's setting, on unless switched off. Pass false for a site whose links change state when requested. |