Follow an audit
Read an audit's status and live progress: pages fetched, the current speed, the site's response time and the issues found so far.
GEThttps://rankfield.dev/v1/site-audit/{id}
Poll every few seconds while status is queued, running or postPass. Issue counts are live, and every result can be read during the crawl.
Parameters
Headers
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
Authorization | string | Yes | – | Bearer followed by your API key. See Authentication. |
Path parameters
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
id | string | Yes | – | The audit's id, from Audit a website. |
Response
| Field | Type | Description |
|---|---|---|
audit | object | As Audit a website answers. |
audit.progress.phase | string | queued, probes (robots.txt, the homepage, how the site answers a page that does not exist, its http and www variants, llms.txt), crawl (sitemaps, pages and resources), postPass (the site-wide checks) or done. |
audit.progress.fetched, audit.progress.queued, audit.progress.known | integer | Pages fetched, waiting, and known so far. |
audit.progress.pagesPerSecond, audit.progress.rate | number | Pages fetched a second, and the speed the brake allows now (fetches a second). |
audit.progress.ttfbP50Ms, audit.progress.baselineMs | number | null | The site's median time to first byte now, and at the start: a slower site slows the audit. |
audit.progress.errors, audit.progress.halvings, audit.progress.pauses | integer | Failed fetches, and how often the speed was halved or the crawl paused for the site's sake. |
audit.progress.etaSeconds | integer | null | An estimate of the time left: the pages still to fetch (up to maxPages of those known so far) at the current speed. null while the site makes us wait. |
audit.progress.siteHold | object | null | While the site makes us wait: {until, seconds, reason, status}. reason is rateLimited (it answered 429 or 503, and status says which; we wait for its Retry-After, 30 seconds when it gives none, 5 minutes at most) or siteErrors (we paused after errors). until is when we go on, in Unix milliseconds, and seconds how long that is from now. |
audit.progress.rateLimited | integer | How many times the site answered 429 or 503. |
audit.progress.issues, audit.counts.issues | object | Issues found so far, per severity (error, warning, notice): issueTypes, the kinds of issue, and affectedUrls, URL–issue pairs (a URL with three issues counts three times). |
audit.counts.health | object | {score, urlsWithErrors, urlsWithoutErrors, internalUrls}: the health score, the share of crawled internal URLs with no error-level issue, 0 to 100, with its parts. Site-wide findings don't count per URL. |
audit.counts.inventory | object | What was crawled, apart from issues: internal (every crawled URL of the site), htmlPages (HTML pages that answered 200), indexable, documents (Markdown, PDF and other files, which are not HTML pages), redirects, errors, resources (the site's images, scripts and stylesheets), disallowed (by robots.txt), notFetched, known, sitemapUrls, externalChecked (external URLs given a status check), externalBroken (the broken ones), externalUnchecked ({total, excluded, robotsDisallowed, botBlocked}: external URLs we did not check, on sites we never fetch, disallowed by robots.txt, or refused by bot protection, never counted as broken) and byStatus. |
Your audits
GET /v1/site-audit lists the audits your key started, newest first, each as above.
Stop an audit
POST /v1/site-audit/{id}/cancel stops the crawl. What was found stays readable, and the site-wide checks run on it (stoppedBy: ["canceled"]).
Errors
| Status | Code | When |
|---|---|---|
| 401 | unauthorized | No valid API key. |
| 404 | not_found | No audit with this id for this key (only the key that started an audit can read it), an unknown issue, or a page that is not in the audit. |
| 500 | internal | Our bug. Retry. |
| 503 | unavailable | New audits are paused while the service is short of storage, or it is restarting. Retry after Retry-After. |
MCP
On the MCP server, the tools for this are site_audit_list, site_audit_status and site_audit_cancel.