> 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: start one, then poll until the status is complete or error. Full-platform audits are included in pooled usage; failed work does not consume completed-work usage.

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**.

## Usage model

Each audit is included in full-platform pooled usage and follows a durable asynchronous lifecycle:

1. **Reserved** at start. The pending operation is reflected in the account's pooled window so concurrent callers see accurate capacity.
2. **Recorded** on full success. The reservation is finalized once the audit reaches `complete` status.
3. **Released** on any non-success exit — a crawlability/indexability/retrievability gate failure, a vendor timeout, or an internal error.

If a pooled window is exhausted, the create call returns `429 usage_limit_reached` with a recovery time before any audit work starts.

## 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",
  "usage_impact": { "level": "standard", "included": true },
  "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 pending usage 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.                           |
| 429  | `usage_limit_reached` | A pooled on-demand window has reached its current limit; wait until the returned recovery time. |
| 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.
* [API usage, rate limits, and errors](/api/api-credits-rate-limits-and-errors.md) — Pooled usage windows, rate limits, and error codes.
* [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.