Skip to content

Site audits

A site audit checks a sample of pages from one site and returns one site report: risk per policy, URL patterns, worst pages and a site verdict. The model answers 0/1 per page and rule; all numbers are computed by code.

The flow has two steps: preview (count pages and group them into URL patterns), then select and run.

1. Preview

curl -H "Authorization: Bearer $KEY" -H 'content-type: application/json' \
  -d '{"site": "example.com"}' https://judge.example.com/v1/audits/site/preview

Sources (one of):

  • site - domain or page URL; the sitemap is read from robots.txt (Sitemap:) or /sitemap.xml.
  • sitemap_url - a direct sitemap or sitemap index.
  • urls - your own list of URLs. Duplicates, invalid and private addresses are skipped (rejected); with same_site: true (default) only URLs from the host of the first URL are kept.
  • items - bulk import: [{"url": "…", "html": "…"}]. Items with html are judged from that HTML without fetching; items without html are fetched. HTML limits are the same as for POST /v1/jobs (per item and in total, 413 item_too_large).

/path and /path/ count as the same URL (many CMS serve both); send distinct_slash: true to keep them apart.

In the panel you can upload a TXT file (one URL per line), a CSV with columns url and optional html (use standard CSV quoting for HTML), or a ZIP with index.csv (url,filename) and the .html files.

Response: preview_id, total, rejected, and patterns - each with count, lastmod_min, lastmod_max and up to three samples. A pattern replaces variable path segments with <n>, <date> and <slug> (e.g. /news/<slug>).

2. Select, estimate, run

Send the same body to /v1/audits/site/estimate (no job is created) and then to /v1/audits/site:

{
  "preview_id": "…",
  "site": "example.com",
  "scope": {"exclude_patterns": ["/people/<slug>"], "exclude": ["/tag/*"], "include": [], "exclude_urls": []},
  "pages": 30,
  "strategy": "newest+stratified",
  "seed": 20261013,
  "preset": "quick",
  "rules": ["SP-KWS-REPEAT", "SP-AFF"]
}
  • Scope: include_patterns / include (empty = all), then exclude_patterns, exclude and exclude_urls. Text rules are globs (*, ?): starting with / they match the path (/people/*), otherwise the full URL. Regular expressions are not accepted.
  • Strategy: newest+stratified (a third newest by lastmod, the rest stratified random per pattern), stratified (random per pattern), newest (by lastmod), all (all selected, up to pages). The same seed and URL list give the same sample.
  • Estimate: cost_usd = pages × price per page (cost_per_page_usd: one full mode Spam $0.0300, Quality $0.0300 or Helpful content $0.0150; several full modes = their sum, never more than the full audit $0.0650; another selection: Lite $0.0200 up to 40 rules, otherwise $0.0650; +$0.0015 fetch per page without your HTML, +$0.0060 per fetched page with render_js on or auto, refunded for pages that were not rendered; see Billing and Fetching), plus time. Prices come from the versioned price list. preset only affects the estimate; send rules to choose rules. categories (["spam", "quality", "helpful"], default all) narrows the rules and the estimate; the findings CSV has a category column and the page CSV a helpful_level column.
  • preview_id reuses the URL list (and imported HTML) from step 1 for a limited time, only for the same user or API key and project. With an expired id the site is read again; an import must be sent again (preview_expired).
  • The estimate shows with_html - selected pages that will be judged from your HTML.

The audit stores the selection (source, patterns and rules, estimate) and shows it in the site report. Poll GET /v1/audits/{id} for progress. Errors: invalid_url, item_too_large, preview_expired, invalid_scope, empty_selection, sitemap_not_found, audit_too_large, quota_exceeded, queue_unavailable.

In the panel: New site audit → enter a site or upload a file → tick patterns, add include/exclude rules, set pages and preset → check the estimate → Run audit.