Skip to main content

​
Overview

The Site Audit API runs Scrunch’s AI search readiness audit against any URL on a brand’s domain. Each audit fetches the page, runs the same checks that power the Site Audit stage of the optimize-and-deploy pipeline, and returns a per-check result, an overall score, and a rendered preview of what AI crawlers see. Use it to audit pages on demand from your own automation — for example, after a publish, as part of a CI gate, or to backfill audits for a list of priority URLs.

​
What the Site Audit API includes

  • Queue one or many URLs for audit in a single call
  • Audit status and timestamps (pending, running, completed, failed)
  • Per-check results for the AI search readiness suite (robots, rendering, schema, content quality, and more)
  • An overall audit score
  • An AI preview (markdown) showing what AI crawlers extract from the page
  • A visitor preview image for the rendered page
  • Filtering and pagination over the brand’s audit history
Results land in the Scrunch dashboard’s Site Audit views and fire the audit.completed webhook on completion.

​
When to use the Site Audit API

Use the Site Audit API when you need to:
  • Trigger an audit immediately after publishing or updating a page
  • Re-audit a set of priority URLs on a schedule
  • Pull audit results into a custom dashboard or report
  • Programmatically gate a deploy on the audit outcome
For audits across the brand’s full sitemap, use the Sitemap API — every page in the sitemap already carries its most recent audit score.

​
Endpoints

MethodPathPurpose
POST/{brand_id}/page-auditsQueue one or more URLs for audit.
GET/{brand_id}/page-auditsList audits in reverse chronological order.
GET/{brand_id}/page-audits/{page_audit_id}Get a single audit, including check results.
POST requires a bearer token with configure scope. The GET endpoints require query scope. See Authentication. URLs are normalized and deduplicated before being queued. URLs outside the brand’s registered domains are rejected.

​
Filters

The list endpoint supports:
FilterDescription
statusRestrict to pending, running, completed, or failed.
urlCase-insensitive substring match on the audited URL.
limitPage size (default 100).
offsetOffset for pagination.

​
Example: queue audits

curl -X POST \
  "https://api.scrunchai.com/v1/1234/page-audits" \
  -H "Authorization: Bearer $SCRUNCH_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": [
      "https://example.com/products/widgets",
      "https://example.com/blog/launch"
    ]
  }'
Response: 
[
  {
    "url": "https://example.com/products/widgets",
    "page_audit_id": "01J9Z4K8R0G6M1Q3VN7N0H4T2A"
  },
  {
    "url": "https://example.com/blog/launch",
    "page_audit_id": "01J9Z4K8R0G6M1Q3VN7N0H4T2B"
  }
]
Audits start pending. Poll the detail endpoint or subscribe to the audit.completed webhook to know when results are ready.

​
Example: fetch an audit result

curl -X GET \
  "https://api.scrunchai.com/v1/1234/page-audits/01J9Z4K8R0G6M1Q3VN7N0H4T2A" \
  -H "Authorization: Bearer $SCRUNCH_API_TOKEN"
A completed response carries the per-check results, an overall score, and previews: 
{
  "url": "https://example.com/products/widgets",
  "status": "completed",
  "result": {
    "version": 2,
    "checks": [
      { "id": "robots_allows_ai", "passed": true, "score": 1.0 },
      { "id": "renders_without_js", "passed": false, "score": 0.0 }
    ],
    "visitor_preview_image_url": "https://...",
    "ai_preview_markdown": "# Widgets\n\nOur flagship..."
  },
  "created_at": "2026-06-05T14:02:00Z",
  "updated_at": "2026-06-05T14:02:41Z"
}
While the audit is still in flight, status is pending or running and result is null.

​
Example: list recent failed audits

curl -X GET \
  "https://api.scrunchai.com/v1/1234/page-audits?status=failed&limit=20" \
  -H "Authorization: Bearer $SCRUNCH_API_TOKEN"

​
Limits and behavior

  • POST accepts up to 100 URLs per call. Submit larger batches across multiple requests.
  • Submissions are rate-limited at 60 audits per minute per brand.
  • URLs are normalized (trailing slash, casing) and deduplicated before queueing, so resubmitting the same URL in a batch returns a single ID.
  • Audits run asynchronously. Typical completion is under a minute; complex pages can take longer.
  • Audits older than the brand’s retention window are pruned from the list endpoint.

​
Best practices

  • Prefer the audit.completed webhook over polling — it fires the moment results are available.
  • Store page_audit_id alongside your internal record so you can correlate webhook deliveries back to the URL that triggered them.
  • Use the url filter on the list endpoint to find the latest audit for a specific page without scanning history.
  • For end-to-end “audit, optimize, deploy” automation, use the optimize-and-deploy pipeline instead of orchestrating these endpoints by hand.