Skip to content

Page Auditor

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

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

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

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

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.
Terminal window
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"
}'
{
"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"
}
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

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.

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

{
"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 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
Status Code When
400 invalid_input Missing or malformed audit_id
404 not_found Audit does not exist or belongs to another organization

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

List recent audits, most recent first.

Required scope: page_audit:read

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
{
"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"
}

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.

{ "success": true, "audit_id": "8c2a...uuid" }
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