> For the complete documentation index, see [llms.txt](https://help.rankability.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.rankability.com/api/api-page-auditor.md). # 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, 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} Authorization: Bearer rk_live_YOUR_KEY ``` Status moves through these stages: `pending` → `crawling` → `researching` → `scoring` → `complete` (or `error`). Poll every 5–10 seconds until you see a terminal status. ### 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&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. Results are sorted by most recent first. ## 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)](/api/mcp-getting-started.md) for setup. ## Related articles * [Getting started with the API](/api/api-getting-started.md) — Overview of the agent API and authentication. * [Authentication and API keys](/api/api-authentication.md) — How to create keys and add scopes. * [Credits, rate limits, and errors](/api/api-credits-rate-limits-and-errors.md) — Per-plan rate limits and a full error code reference. * [Search Intelligence API endpoints](/api/api-search-intelligence.md) — The other recently-published agent endpoint. * [Connecting Rankability to AI assistants (MCP)](/api/mcp-getting-started.md) — Use the equivalent tools from Claude, Cursor, and Windsurf. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://help.rankability.com/api/api-page-auditor.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.