> 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 asynchronous on-page audits through the Agent API and monitor their pooled usage lifecycle.

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"`.                         |
| `PUT /api/agent/v1/page-auditor/audits/batch`     | `page_audit:write` | Dry-run or start/resume up to 25 audits under one durable job ID.                                          |
| `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 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
Idempotency-Key: stable-page-audit-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; it is required for every create call. Identical retries return the same durable audit across process restarts and concurrent delivery. Reusing a key with different inputs returns `409 idempotency_conflict`.

## Run a batch safely

Use `PUT /api/agent/v1/page-auditor/audits/batch` with a stable `Idempotency-Key`, a required `client_id`, one to 25 audit items, and `dry_run: true`. The dry run validates every URL and returns the deterministic job/audit IDs plus the complete usage impact without writing. After approval, repeat the same body and key with `dry_run: false`. Poll the returned `job_id` through `GET /api/agent/v1/jobs/{job_id}`; retries resume the same batch and only start missing items. To reconcile several Page Auditor and related Tracker, Researcher, Optimize, or Site Auditor jobs together, send one to 50 IDs to the read-only `POST /api/agent/v1/jobs/status` endpoint. Normalized responses include progress, terminal reason, output ID, timestamps, and the next recommended polling interval.

For browser-free synthesis, `GET /api/agent/v1/exports?client_id=...&type=audit_results&artifact_type=page_audit|site_audit|tracker_project&format=json|csv` returns bounded result rows with `limit` and `offset` pagination. The shared schema includes target and observed ranking URLs, platform position, brand mention/citation state, source URLs, score, and run date where those values apply. Completed outputs are the default; set `include_incomplete=true` only when incomplete evidence is explicitly required. Use `type=audit_manifest` for the lifecycle/configuration inventory instead. An API key sees only artifact families covered by its matching Page Auditor, Site Auditor, or Tracker read scope.

## 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).                  |
| 400  | `idempotency_key_required` | A run or batch omitted `Idempotency-Key`.                                                       |
| 409  | `idempotency_conflict`     | A key was reused for a different run or batch request.                                          |
| 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_batch_upsert` — Dry-run or start/resume a durable multi-page batch.
* `page_audit_get` — Fetch an audit by ID (mirrors `GET /page-auditor/audits/:id`).
* `page_audit_list` — List audits (mirrors `GET /page-auditor/audits`).
* `jobs_status`, `audit_manifest_get`, and `exports_get` — Reconcile work and retrieve structured lifecycle evidence without browser steps.

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.