Page Auditor API endpoints

Run on-page audits via the agent API. Audits are asynchronous: kick one off, then poll until status is complete or error. Each audit reserves a fixed credit charge that's released on gate failure…

Run on-page audits via the agent API. Audits are asynchronous: kick one off, then poll until status is complete or error. Each audit reserves a fixed credit charge that's released on gate failure, vendor timeout, or error.

The Page Auditor agent API lets you run an on-page audit for any public URL against a target keyword and retrieve the full result programmatically. It mirrors the in-app Page Auditor flow: each audit fetches the page, scores it across technical health, agent readiness, and content quality, and runs SERP-aware gates for crawlability, indexability, and retrievability.

Endpoints at a glance

Method & Path	Scope	Purpose
POST /api/agent/v1/page-auditor/audits	page_audit:write	Start a new audit. Returns immediately with an audit_id and status: "pending".
GET /api/agent/v1/page-auditor/audits/:audit_id	page_audit:read	Fetch a single audit by ID. Use this to poll for completion.
GET /api/agent/v1/page-auditor/audits	page_audit:read	List audits for your organization. Supports client_id, status, limit, and offset query parameters.

Authentication and scopes

All three endpoints use the standard agent API auth: Authorization: Bearer rk_live_.... Add the page_audit:write scope to your API key to start audits, and page_audit:read to retrieve them. Manage scopes in Settings > API keys.

Credit model

Each audit costs 150 credits and follows a reserved-charge lifecycle:

1. Reserved at start. The credits are held against your organization the moment POST /audits succeeds, so concurrent callers see an accurate balance.

2. Charged on full success. The reservation is finalized once the audit reaches complete status.

3. Released (refunded) on any non-success exit — a crawlability/indexability/retrievability gate failure, a vendor timeout, or an internal error. You are never charged for an audit Rankability could not deliver.

If your account does not have enough credits to cover the reservation, the create call returns 402 insufficient_credits before any DB row is written.

Start an audit

POST /api/agent/v1/page-auditor/audits
Authorization: Bearer rk_live_YOUR_KEY
Content-Type: application/json

{
  "url": "https://example.com/blog/seo-guide",
  "keyword": "seo guide",
  "location": "United States",
  "intent": "informational",
  "client_id": "8f1a2b3c-..."
}

Field	Type	Required	Description
url	string (URL)	Yes	The public URL to audit. Must be http or https; private/internal hosts are rejected (SSRF protection).
keyword	string	Yes	The target keyword the page should rank for. Max 500 characters.
location	string	No	Optional location for SERP context (e.g. "United States"). Max 200 characters.
intent	enum	No	One of informational, commercial, transactional, navigational. If omitted, the auditor detects intent automatically.
client_id	UUID	No	Associates the audit with a client in your organization. The client must belong to your org.

Response (201 Created)

{
  "audit_id": "1f8d3c5e-7e2a-4d2f-9c0b-2c8c9b9c5fa1",
  "status": "pending",
  "credits_reserved": 150,
  "keyword": "seo guide",
  "url": "https://example.com/blog/seo-guide",
  "client_id": "8f1a2b3c-...",
  "created_at": "2026-05-12T15:30:00.000Z"
}

The endpoint returns immediately. Audit work happens in the background; typical end-to-end run time is 60–180 seconds.

Idempotency

Send an Idempotency-Key header to make the create call safe to retry. Identical retries within the cache window return the original response without starting a second audit.

Poll for completion

GET /api/agent/v1/page-auditor/audits/{audit_id}?view=status
Authorization: Bearer rk_live_YOUR_KEY

Status moves through these stages: pending → crawling → researching → scoring → complete (or error). Poll the bounded view=status response every 5–10 seconds until you see a terminal status, then omit view or request view=full for the complete analysis.

Nested audit data uses canonical snake_case by default. Use naming=legacy only when maintaining a consumer of the earlier mixed-casing nested payload.

Successful response

{
  "audit_id": "1f8d3c5e-...",
  "status": "complete",
  "keyword": "seo guide",
  "url": "https://example.com/blog/seo-guide",
  "location": "United States",
  "intent": "informational",
  "client_id": "8f1a2b3c-...",
  "overall_score": 82,
  "section_scores": { "technical_health": 88, "agent_readiness": 79, "content_quality": 80 },
  "score_details": { ... },
  "gate_results": {
    "crawlability": { "passed": true },
    "indexability": { "passed": true },
    "retrievability": { "passed": true }
  },
  "technical_health": { ... },
  "agent_readiness": { ... },
  "page_title": "The Complete SEO Guide for 2026",
  "meta_description": "Everything you need to know...",
  "h1_tags": ["The Complete SEO Guide for 2026"],
  "h2_tags": ["What is SEO?", "On-page SEO basics", "..."],
  "word_count": 2450,
  "page_size_bytes": 184320,
  "schema_markup_types": ["Article", "FAQPage"],
  "quality_analysis": { ... },
  "error_message": null,
  "started_at": "2026-05-12T15:30:02.000Z",
  "completed_at": "2026-05-12T15:31:48.000Z",
  "created_at": "2026-05-12T15:30:00.000Z",
  "updated_at": "2026-05-12T15:31:48.000Z"
}

Gate failure

If the page fails one of the SERP-aware gates (crawlability / indexability / retrievability), the audit terminates with status: "error", the gate_results object spells out which gate failed and why, and the credit reservation is released. error_message contains a short explanation.

List audits

GET /api/agent/v1/page-auditor/audits?client_id={uuid}&status=complete&view=compact&limit=50&offset=0
Authorization: Bearer rk_live_YOUR_KEY

• client_id (optional) — Filter to a specific client.

• status (optional) — Filter by audit status (e.g. complete, error).

• limit (optional) — Default 50, max 100.

• offset (optional) — For pagination.

• view (optional) — compact by default; full includes all stored analysis subtrees.

• fields (optional) — Comma-separated top-level field selection such as audit_id,status,overall_score,completed_at.

Results are sorted by most recent first. Pagination includes total and has_more. Keep the compact default for discovery; fetch one completed audit by ID for full analysis.

Error codes

HTTP	Code	When
400	invalid_input	Missing/invalid url or keyword, non-HTTP protocol, or private host (SSRF).
401	unauthorized	Missing or invalid Authorization header.
403	forbidden	API key is missing the page_audit:write or page_audit:read scope.
402	insufficient_credits	Not enough credits to reserve the audit charge.
404	not_found	Audit ID not found, or client_id not in your org.
429	rate_limited	Per-minute rate limit exceeded.

End-to-end example

1. POST /api/agent/v1/page-auditor/audits   → {"audit_id": "...", "status": "pending"}
2. GET  /api/agent/v1/page-auditor/audits/:id (every 5s)
                                            → status: "crawling" → "researching" → "scoring"
3. GET  /api/agent/v1/page-auditor/audits/:id
                                            → status: "complete" + scores + analysis

MCP equivalents

If you've connected Rankability to Claude Desktop, Cursor, or Windsurf via MCP, the same operations are exposed as natural-language tools:

• page_audit_run — Start a new audit (mirrors POST /page-auditor/audits).

• page_audit_get — Fetch an audit by ID (mirrors GET /page-auditor/audits/:id).

• page_audit_list — List audits (mirrors GET /page-auditor/audits).

See Connecting Rankability to AI assistants (MCP) for setup.

Related articles

• Getting started with the API — Overview of the agent API and authentication.

• Authentication and API keys — How to create keys and add scopes.

• Credits, rate limits, and errors — Per-plan rate limits and a full error code reference.

• Search Intelligence API endpoints — The other recently-published agent endpoint.

• Connecting Rankability to AI assistants (MCP) — Use the equivalent tools from Claude, Cursor, and Windsurf.