---
title: "Page Auditor"
description: "Run single-page and batch AEO and SEO audits and read the results."
canonical_url: "https://developers.rankability.com/guides/page-auditor"
section: "Guides"
last_updated: 2026-11-14
---

# Page Auditor

Run single-page and batch AEO and SEO audits and read the results.

## Page Auditor

The Page Auditor scores a single URL against a target keyword across crawlability, indexability, retrievability (the three "agent gates"), keyword placement, entity coverage, performance (PSI), page size, schema markup, technical health, and AI-driven quality checks. It is the same engine that powers the in-app Page Auditor at `/dev/page-auditor`.

**Pricing.** Each successful audit costs **150 credits**. Credits are reserved when you start an audit and:

- **Charged** only when the audit completes with a full score (status `complete` and `overall_score` is non-null).
- **Refunded** automatically (no credits charged) when the page fails one of the three agent gates (`status: "complete"` with `overall_score: 0`), when the upstream research vendor errors or times out, or when the audit ends with `status: "error"`.

PageSpeed Insights (Core Web Vitals) is a soft-dependency: if PSI is unreachable or slow, the audit still completes with a `null` performance section and the standard 150-credit charge applies — performance simply does not factor into the score for that run.

Audits run asynchronously. Start one with `POST /page-auditor/audits`, then poll `GET /page-auditor/audits/:audit_id` until `status` is `complete` or `error` (typically 60–180 seconds).

### Scopes

| Scope | Grants |
|---|---|
| `page_audit:write` | Start audits via `POST /page-auditor/audits` |
| `page_audit:read` | Read audits via `GET /page-auditor/audits` and `GET /page-auditor/audits/:audit_id` |

## Page Auditor — Start audit

`POST /api/agent/v1/page-auditor/audits`

Reserve 150 credits and start a new audit. Returns immediately with `status: "pending"`. `Idempotency-Key` is required and derives the durable audit ID, so a retry returns the same audit across process restarts and concurrent delivery. Reusing a key for different inputs returns `409 idempotency_conflict`.

**Required scope:** `page_audit:write`

### Request body

| Field | Type | Required | Description |
|---|---|---|---|
| `keyword` | string | Yes | Target keyword the page should rank for. Max 500 chars. |
| `url` | string (URL) | Yes | Public URL to audit. Must use `http` or `https`. Private/loopback hosts are rejected. |
| `location` | string | No | Optional location for SERP context (e.g. `"United States"`). Max 200 chars. |
| `intent` | enum | No | One of `informational`, `commercial`, `transactional`, `navigational`. If omitted, Rankability infers it from the keyword, URL, and location (for example, a service keyword with a city, state, or "near me" is treated as `transactional`, which uses the local-service rubric). The response reports it as `detected_intent` with `intent_source` (`provided` or `inferred`). Pass `intent` to override. |
| `client_id` | UUID | No | Optional client to associate the audit with. Must belong to your organization. |

### Example request

```bash
curl -X POST https://yourapp.com/api/agent/v1/page-auditor/audits \
  -H "Authorization: Bearer rk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "keyword": "best running shoes 2026",
    "url": "https://example.com/best-running-shoes",
    "location": "United States",
    "intent": "commercial"
  }'
```

### Response (201 Created)

```json
{
  "audit_id": "8c2a...uuid",
  "status": "pending",
  "credits_reserved": 150,
  "keyword": "best running shoes 2026",
  "url": "https://example.com/best-running-shoes",
  "intent": "commercial",
  "detected_intent": "commercial",
  "intent_source": "provided",
  "client_id": null,
  "created_at": "2026-04-29T15:00:00.000Z"
}
```

### Errors

| Status | Code | When |
|---|---|---|
| 400 | `invalid_input` | Missing/invalid fields, non-public URL, or bad protocol |
| 402 | `insufficient_credits` | Org does not have 150 credits available (includes pending reservations) |
| 404 | `not_found` | `client_id` does not exist or belongs to another organization |
| 409 | `idempotency_conflict` | The same idempotency key was reused with different audit inputs |

## Page Auditor — Batch upsert

`PUT /api/agent/v1/page-auditor/audits/batch` accepts a required `client_id`, one to 25 `{url, keyword, location?, intent?}` items, and a required `Idempotency-Key`. Send `dry_run: true` first to receive deterministic audit IDs, configuration hashes, existing/missing counts, and the complete usage estimate without writing or reserving usage. Repeat with the same key and `dry_run: false` after approval to start only missing items. The returned `job_id` is stable; poll it through `GET /api/agent/v1/jobs/:job_id`.

The batch validates tenant ownership, public URLs, duplicates, total capacity, and all legacy credit availability before launching work. Setup failures release newly created reservations and remove newly created audit rows. A retry resumes the same batch rather than creating another set of audits.

`GET /api/agent/v1/jobs/:job_id` normalizes Page Auditor, Page Auditor batch,
Optimize, Researcher, Tracker scan, and Site Auditor status. Responses include
`terminal`, `terminal_reason`, `output_id`, timestamps, available progress, and
`next_poll_after_seconds`. Use the read-only `POST /api/agent/v1/jobs/status`
with `{ "job_ids": [...] }` to reconcile one to 50 IDs in request order;
unknown or cross-organization IDs return per-item `not_found` state without
exposing another tenant's records.

For synthesis-ready output, call `GET /api/agent/v1/exports` with
`type=audit_results`, `artifact_type=page_audit|site_audit|tracker_project`,
`format=json|csv`, and bounded `limit`/`offset` pagination. Normalized rows
include target and observed ranking URLs, platform position, mention/citation
state, source URLs, score, and run date where the artifact supports those
fields. Completed outputs are the default; set `include_incomplete=true` only
when incomplete evidence is explicitly required. `type=audit_manifest` remains
the lifecycle/configuration inventory.
Manifest responses include only artifact families allowed by the API key's read
scopes; requesting a specific result or manifest family without its matching
scope returns `403 forbidden`.

## Page Auditor — Get audit

`GET /api/agent/v1/page-auditor/audits/:audit_id`

Fetch a single audit. Poll with `?view=status` until `status` is `complete` or `error`, then request `view=full` (the default) for the analysis. Nested audit objects use canonical `snake_case` by default; `naming=legacy` preserves the earlier mixed-casing representation.

**Required scope:** `page_audit:read`

### Response

```json
{
  "audit_id": "8c2a...uuid",
  "status": "complete",
  "keyword": "best running shoes 2026",
  "url": "https://example.com/best-running-shoes",
  "location": "United States",
  "intent": "commercial",
  "client_id": null,
  "overall_score": 78,
  "section_scores": [ /* per-section scoring */ ],
  "score_details": { /* keyword placement, entity coverage, performance, etc. */ },
  "gate_results": { /* crawlability, indexability, retrievability */ },
  "technical_health": { /* health checks */ },
  "agent_readiness": { /* agent-readiness module output */ },
  "page_title": "Best Running Shoes for 2026",
  "meta_description": "...",
  "h1_tags": ["..."],
  "h2_tags": ["..."],
  "word_count": 2143,
  "page_size_bytes": 187432,
  "schema_markup_types": ["Article", "Product"],
  "quality_analysis": { /* AI quality rubric */ },
  "error_message": null,
  "started_at": "2026-04-29T15:00:01.000Z",
  "completed_at": "2026-04-29T15:01:42.000Z",
  "created_at": "2026-04-29T15:00:00.000Z",
  "updated_at": "2026-04-29T15:01:42.000Z"
}
```

### Status values

| Status | Meaning | Credits status |
|---|---|---|
| `pending` | Reserved, queued, not yet started | Reserved |
| `crawling` / `researching` / `scoring` | Audit is in flight | Reserved |
| `complete` (with `overall_score > 0`) | Audit finished successfully | **Charged** |
| `complete` (with `overall_score == 0`) | Page failed an agent gate (crawlability / indexability / retrievability) | Released — no charge |
| `error` | Vendor timeout or unexpected failure | Released — no charge |

### Errors

| Status | Code | When |
|---|---|---|
| 400 | `invalid_input` | Missing or malformed `audit_id` |
| 404 | `not_found` | Audit does not exist or belongs to another organization |

## Page Auditor — List audits

`GET /api/agent/v1/page-auditor/audits`

List recent audits, most recent first.

**Required scope:** `page_audit:read`

### Query parameters

| Parameter | Type | Default | Description |
|---|---|---|---|
| `client_id` | UUID | — | Filter by client |
| `status` | enum | — | Filter by `pending`, `crawling`, `researching`, `scoring`, `complete`, or `error` |
| `limit` | number | 50 | Max 100 |
| `offset` | number | 0 | For pagination |
| `view` | enum | `compact` | `compact` or `full` |
| `fields` | CSV | — | Explicit top-level field selection; overrides the view field set |
| `naming` | enum | `snake_case` | Use `legacy` only for mixed-casing backward compatibility |

### Response

```json
{
  "audits": [
    {
      "audit_id": "8c2a...uuid",
      "status": "complete",
      "keyword": "best running shoes 2026",
      "url": "https://example.com/best-running-shoes",
      "overall_score": 78,
      "created_at": "2026-04-29T15:00:00.000Z",
      "completed_at": "2026-04-29T15:01:42.000Z"
    }
  ],
  "pagination": { "limit": 50, "offset": 0, "count": 1, "total": 1, "has_more": false },
  "view": "compact"
}
```

## Page Auditor — Delete an audit

`DELETE /api/agent/v1/page-auditor/audits/:audit_id`

Permanently delete a finished audit and free up clutter from old runs. This lets assistants prune stale audits the same way they prune finished Site Auditor projects.

**Required scope:** `page_audit:write`

Only **terminal** audits may be deleted: `status` must be `complete` or `error`. An audit in any other status (`pending`, `crawling`, `researching`, `scoring`) is still running with credits reserved against it — the endpoint returns `409 conflict`; wait for it to finish, then delete.

### Response

```json
{ "success": true, "audit_id": "8c2a...uuid" }
```

### Errors

| Status | Code | When |
|---|---|---|
| 400 | `invalid_input` | Missing or malformed `audit_id` |
| 404 | `not_found` | Audit does not exist or belongs to another organization |
| 409 | `conflict` | Audit is still in progress (not `complete`/`error`) — wait for it to finish |
