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:

Reserved at start. The pending operation is reflected in the account’s pooled window so concurrent callers see accurate capacity.
Recorded on full success. The reservation is finalized once the audit reaches complete status.
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, 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	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",
  "intent": "informational",
  "detected_intent": "informational",
  "intent_source": "provided",
  "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",
  "detected_intent": "informational",
  "intent_source": "provided",
  "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) for setup.

Getting started with the API — Overview of the agent API and authentication.
Authentication and API keys — How to create keys and add scopes.
API usage, rate limits, and errors — Pooled usage windows, rate limits, and error codes.
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.