Skip to main content
POST
Perform a comprehensive SEO audit on a website
Run SEO checks for one page or crawl a site for a broader audit. Send the options in the JSON body. GET /v3/seo-audit supports the same audit with query parameters; it requires url, because urls (batch) is POST only. Single-page audits stream newline-delimited JSON (application/x-ndjson). Progress lines contain status; the final line contains url, seoAudit, and screenshot. The seoAudit object includes overall and category scores, individual checks, and an audit summary. Read the final line to get the completed result. If an error occurs after streaming begins, it arrives as an error line while the HTTP status remains 200. Preview and multiple-page modes return ordinary JSON. Their shape depends on the selected options: a preview includes a suggested brand, a selected-page audit includes auditStatus, totalPages, acceptedUrls, and acceptedAt, and a synchronous multiple-page audit includes results. Full-site background audits also include acceptedAt. Background audits do not return a job ID. Poll GET /v3/seo-audit/active-run?teamId=<teamId> for the team’s audit status, progress, and in-flight page URLs. auditProgress is weighted by the target-page counts of currently active runs. It is not a cumulative percentage of every run started in the browser, so it may drop when one of several runs finishes. Body and query fields: url (required unless urls is sent), urls (POST only; audit selected pages, requires teamId), teamId (required for background and crawlOnly runs, and the caller must belong to the team), auditType (single default, or multiple), async (multiple mode; defaults to true), crawlOnly (discover pages without auditing them), preview, brandName, includeTags, excludeTags. Each audited page counts against your plan’s page-audit allowance. If it is exhausted, the call returns 402. Starting a full-site audit while one is already running returns 409.
A website-wide audit can take time and may continue in the background. Check the active-run endpoint before starting another run for the team.

Authorizations

Authorization
string
header
required

Your SnowSEO API key (sk_...).

Body

application/json
url
string

URL to audit (https:// prefixed automatically)

teamId
string

Team ID (required for async multiple mode)

auditType
enum<string>
default:single

Audit mode: single page or deep multi-page crawl

Available options:
single,
multiple
async
enum<string>
default:true

Enable async background processing (multiple mode only)

Available options:
true,
false
includeTags

HTML tags to include during crawl

excludeTags

HTML tags to exclude during crawl

selection
object
preview
urls
string[]

Batch of URLs to audit (alternative to url for Audit Selected). Requires teamId.

Minimum array length: 1

Response

Preview and multi-page requests return JSON. Single-page audits stream status updates followed by the final result as NDJSON.

eligibility
object
units
number
url
string
title
string
suggestedBrand
string
seoAudit
object

Final SEO audit result for a single page.

screenshot
string | null
success
boolean
message
string
totalPages
number
auditStatus
enum<string>
Available options:
running,
idle
acceptedUrls
string[]
acceptedAt
number
results
object[] | null