Start a multi-page crawl of one verified website. It runs in the background and is read back with Get a site audit.

POSThttps://api.rankparse.com/v1/site-audit/runFreeAPI key

Queues a site audit of one website. The crawl runs in the background, usually within a few minutes for a few hundred pages. Poll Get a site audit until audit.status is completed (waiting a minute between checks is plenty).

The website must be verified and the workspace on a paid plan.

Query parameters

site_idstringrequired

A website id from Websites, sent in the query string. A missing, unknown, archived or other workspace's id returns 404 site_audit_site_not_found.

Body parameters

The body is optional JSON.

max_pagesinteger

Crawl at most this many pages. At least 10, and never more than your plan allows (200 on Pro and Lifetime, 500 on Agency): a larger value is lowered to the plan's limit. Defaults to the plan's limit. A value below 10, or one that is not an integer, returns 400 site_audit_invalid_request.

Response

site_idstring

The website.

audit_idstring

The audit that was started, or the one already in progress or just requested.

statusstring

queued (HTTP 202): the audit was started. already_running (HTTP 200): an audit of this website is queued or running, and nothing changed. throttled (HTTP 200): the last audit was requested less than 30 minutes ago, and nothing changed.

max_pagesinteger

Only with queued: the page budget of this audit.

retry_after_secondsinteger

Only with throttled: seconds until a new audit is accepted.

Behavior and limits

Cost: 0 credits.
One at a time: a website has at most one queued or running audit. Two requests at once start one audit.
Throttle: one new audit per website every 30 minutes, counted from when the last one was requested.
Retention: the 3 newest audits of a website are kept. Starting a new one deletes the oldest beyond that.
Checks run in order: the website must exist, then be verified (400 site_audit_not_verified), then the plan must include audits (403 site_audit_plan_required).
Permissions: needs the site.edit capability.
Rate limit: 60 requests per minute per key. See Rate limiting.

Errors

HTTP	Code	When
400	`site_audit_not_verified`	No verified Google Search Console or Bing Webmaster Tools property is attached to the website.
400	`site_audit_invalid_host`	The website's host cannot be crawled.
400	`site_audit_invalid_request`	The body is not JSON, or `max_pages` is not an integer of at least 10.
401	`invalid_api_key`	Missing, invalid or revoked API key.
403	`capability_missing`	Your workspace role cannot edit websites.
403	`site_audit_plan_required`	The workspace is on the Free plan.
404	`site_audit_site_not_found`	`site_id` is missing or not a website in your workspace.
429	`rate_limited`	More than 60 requests in a minute.

See Errors for the error body format.

MCP tool: run_site_audit (accepts site_id and max_pages).

Site audit

How the crawl works, limits and every issue.

Get a site audit

Progress, score and issues by type.

curl -X POST "https://api.rankparse.com/v1/site-audit/run?site_id=site_abc123" \
  -H "X-API-Key: rp_your_key" \
  -H "Content-Type: application/json" \
  -d '{"max_pages": 100}'

202 Response

{
  "site_id": "site_abc123",
  "audit_id": "aud_Qm3x9bT2kZ7vLw1PdRf8N",
  "status": "queued",
  "max_pages": 100
}

200 already_running

{
  "site_id": "site_abc123",
  "audit_id": "aud_Qm3x9bT2kZ7vLw1PdRf8N",
  "status": "already_running"
}

200 throttled

{
  "site_id": "site_abc123",
  "audit_id": "aud_Qm3x9bT2kZ7vLw1PdRf8N",
  "status": "throttled",
  "retry_after_seconds": 1204
}

403 site_audit_plan_required

{
  "error": "Forbidden",
  "code": "site_audit_plan_required",
  "message": "Site audits are included in the Pro and Agency plans"
}

Run a site audit

Query parametersCopy Anchor Link

Body parametersCopy Anchor Link

ResponseCopy Anchor Link

Behavior and limitsCopy Anchor Link

ErrorsCopy Anchor Link

RelatedCopy Anchor Link