AccessPreflightAPI documentation
Open console
Scan workflows

Scan a whole public website

A whole-site scan creates one parent scn_… resource and durable page work beneath it. Use it when one report must cover a sitemap or a rendered same-origin crawl without creating one customer-visible scan per page.

Create one parent scan

Submit a website root or sitemap URL. max_pages defaults to 25,000 and accepts 1–25,000. Site screenshots are not supported.

{
  "environment": "production",
  "asset": {
    "type": "site",
    "url": "https://example.com/sitemap.xml",
    "viewport": "desktop",
    "max_pages": 10000
  },
  "profiles": ["wcag-2.2-aa-web@latest"],
  "options": {
    "include_repair_plan": true,
    "include_screenshots": false
  }
}

The response has kind: site and one scan ID. Existing scans:write, scans:read, and reports:read scopes authorize the workflow.

Discovery behavior

AccessPreflight checks an explicit sitemap, Sitemap declarations in robots.txt, and /sitemap.xml. Sitemap indexes, gzip, recursion, bytes, and document count are bounded. If no usable sitemap exists, completed pages return rendered links and grow a same-origin crawl frontier.

Discovery:

  • respects the effective redirected origin, robots.txt, safe-egress checks, and redirect validation;
  • identifies the crawler and applies the matching Allow/Disallow rules by longest match;
  • removes fragments and tracking parameters, orders query parameters, and caps query variants per path;
  • scans public HTML pages only;
  • inventories linked PDF and DOCX files as skipped documents;
  • admits no more than max_pages executable pages.

Skipped-document inventory is separately bounded by the same max_pages value. Reaching either bound produces an incomplete result with a stable warning instead of creating unbounded durable work.

When more pages exist, site.truncated is true, warnings contains a stable reason, and the final result is incomplete.

Credits

Sitemap discovery is free. The API reserves the discovered executable-page count before page workers start. Crawl fallback initially reserves the root page, then atomically extends the same pinned reservation before each newly discovered batch becomes schedulable. If the remaining admission-period balance cannot cover a batch, those HTML pages are not queued, discovery is marked truncated, and already completed evidence remains useful.

Only successfully scanned HTML pages settle. Failed, skipped, and cancelled pages release their portion. The reservation remains assigned to the billing period in which the site scan was admitted, including when the seven-day execution window crosses a billing boundary.

Read progress and results

The parent site projection contains discovery method, warnings, deadline, and durable counters for discovered, queued, active, completed, failed, skipped, and cancelled assets.

Use server-side cursor pagination; do not accumulate 25,000 rows in one browser request:

GET /v1/scans/{scan_id}/pages?limit=100&status=completed
GET /v1/scans/{scan_id}/pages/{page_id}
GET /v1/scans/{scan_id}/pages/{page_id}/findings
GET /v1/scans/{scan_id}/issue-groups

The parent findings endpoint also accepts page_id. Every site finding includes its page reference. Completed pages expose lazy JSON and HTML reports.

Aggregate reports

Whole-site reports keep page-level finding instances separate from unique issue groups. The aggregate risk score uses aps-site-risk-1: maximum page risk below 20 successful pages, otherwise the 95th percentile. Incompleteness is reported separately from risk.

Available aggregate artifacts are JSON, HTML, XLSX, evidence, and the complete data ZIP. The XLSX contains Summary, Pages, Issue groups, and bounded representative findings. The deterministic ZIP streams complete NDJSON page, finding, and issue-group datasets. Page and issue-group rows are read through bounded cursors, XLSX sheets are written as streams, and large staged exports use multipart object-storage uploads rather than collecting the complete site result in API memory.

Partial failure and cancellation

Individual transient page failures retry independently up to three attempts. Page failures do not erase successful evidence. After seven days, unfinished work is cancelled and the parent finalizes with result: incomplete.

Cancelling after discovery stops new page scheduling but still creates partial reports from completed pages. The final parent status is cancelled, with a non-null incomplete result and report links. A cancelled site scan without completed discovery has no partial report.

Automated page scans do not certify whole-service or legal compliance. Manual assessment of journeys, states, content, and applicable requirements remains necessary.

Search documentation