> ## Documentation Index
> Fetch the complete documentation index at: https://developers.scrunch.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Site Audit API: Score pages for AI search readiness

> Queue page audits for URLs on your brand's domain and fetch the AI search readiness checks, scores, and previews that power the Site Audit stage.

## 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](/api-reference/optimize-deploy), 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](/api-reference/webhooks/overview) 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](/api-reference/sitemap/overview) — every page in the sitemap already carries its most recent audit score.

***

## Endpoints

| Method | Path                                      | Purpose                                      |
| ------ | ----------------------------------------- | -------------------------------------------- |
| POST   | `/{brand_id}/page-audits`                 | Queue one or more URLs for audit.            |
| GET    | `/{brand_id}/page-audits`                 | List 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](/getting-started/authentication).

URLs are normalized and deduplicated before being queued. URLs outside the brand's registered domains are rejected.

***

## Filters

The list endpoint supports:

| Filter   | Description                                                 |
| -------- | ----------------------------------------------------------- |
| `status` | Restrict to `pending`, `running`, `completed`, or `failed`. |
| `url`    | Case-insensitive substring match on the audited URL.        |
| `limit`  | Page size (default `100`).                                  |
| `offset` | Offset for pagination.                                      |

***

## Example: queue audits

```bash theme={null}
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:**

```json theme={null}
[
  {
    "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

```bash theme={null}
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:

```json theme={null}
{
  "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

```bash theme={null}
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](/api-reference/webhooks/overview) 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](/api-reference/optimize-deploy) instead of orchestrating these endpoints by hand.