Page Auditor
Run single-page and batch AEO and SEO audits and read the results.
Page Auditor
Section titled “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
completeandoverall_scoreis non-null). - Refunded automatically (no credits charged) when the page fails one of the three agent gates (
status: "complete"withoverall_score: 0), when the upstream research vendor errors or times out, or when the audit ends withstatus: "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
Section titled “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
Section titled “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
Section titled “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
Section titled “Example request”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)
Section titled “Response (201 Created)”{ "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
Section titled “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
Section titled “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
Section titled “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
Section titled “Response”{ "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
Section titled “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
Section titled “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
Section titled “Page Auditor — List audits”GET /api/agent/v1/page-auditor/audits
List recent audits, most recent first.
Required scope: page_audit:read
Query parameters
Section titled “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
Section titled “Response”{ "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
Section titled “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
Section titled “Response”{ "success": true, "audit_id": "8c2a...uuid" }Errors
Section titled “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 |
