📌 What this article covers
This guide explains the Site Audit REST API for authenticated Search Atlas accounts: starting a crawl, how crawl_budget is applied, where to read status, settings, and URL issues, and how to recrawl a domain without changing settings or creating an OTTO project. It also covers permissions, quota, archive slots, rate limits, response fields, and subdomains.
🚀 Start an audit
Use POST /api/v2/site-audit/ with your account API credentials. Send the domain you manage and the crawl settings for that run, including crawl_budget. The call creates or updates the Site Audit record only. It does not create an OTTO project, and you should not send OTTO project fields.
A successful response returns the audit identifier, the domain, the accepted crawl budget, and a status such as queued or running. Save the identifier. You need it for later reads and for a recrawl.
📊 Crawl budget on a new domain
Yes. If you send crawl_budget: 25 for a new domain, that audit is capped at 25 URLs. The crawler does not expand to the whole site. A higher plan allowance does not override the value you sent.
- The cap applies only when 25 is within your remaining crawl quota.
- If fewer than 25 URLs of quota remain, the crawl stops when quota runs out.
- Pages that cannot be fetched still count toward the attempt limit for that run.
- Changing the budget later requires a new request. It does not rewrite a crawl already in progress.
⚙️ Read status, settings, and issues
After POST returns an audit id, use the authenticated GET reads for that same audit. The current paths are listed in the in-product API reference so you always call the version tied to your account. Use three separate reads:
- Status returns state, progress, URLs crawled, and whether the run is queued, running, complete, or failed.
- Settings returns the saved domain settings, including the crawl budget used for the latest run.
- URL issues returns the issue list for crawled URLs, including severity and the affected URL.
Do not poll a different domain or another account's audit id. Empty issues usually mean the crawl has not finished or no issues were found.
🛠️ Recrawl without changing settings
To recrawl an existing domain, call POST /api/v2/site-audit/ again for that same domain and audit. Omit settings you do not want to change, and do not send any OTTO project payload. Saved settings, including the existing crawl budget, stay as they are.
- Confirm the domain already has a Site Audit id.
- Send the recrawl request with that domain and audit id only.
- Do not include new settings or an OTTO project.
- Poll the status read until the run completes, then refresh URL issues.
A recrawl replaces the previous run's results for that domain. It does not merge two crawls and it does not create a second project.
💡 Permissions, quotas, slots, and rate limits
The API is for authenticated use by your Search Atlas account. It is not an open public endpoint. You may audit domains you add to your own account. Do not share tokens or audit a site you do not manage.
- Quota: each URL attempted in a crawl counts toward your Site Audit crawl quota. Quota is consumed when the crawl runs, not when you merely save settings.
- Archive and slots: a finished audit uses an active slot until you archive it. Archiving frees the slot. It does not refund URLs already crawled and it does not erase saved settings used for a later recrawl.
- Rate limits: keep one active crawl per domain. Parallel crawls of the same domain can be rejected. If a call is throttled or quota is exhausted, wait and retry later instead of launching another crawl.
🔍 Response fields and subdomain isolation
Create and status responses include the audit id, domain, status, accepted crawl budget, and URLs crawled. The settings read returns the stored settings. The issues read returns one entry per affected URL with the issue type and severity. Extra fields may appear as the API evolves. Ignore fields you do not use.
A root domain and its subdomains are isolated. An audit of example.com does not crawl blog.example.com unless that host is included in the crawl scope or audited as its own domain. Each host has its own status, settings, issues, and quota usage. Archiving one host does not archive the other.
💬 If you still need help
If you need further assistance, open the chat widget in the bottom-right corner of the platform and type human teammate to be instantly connected with a member of our team.