# On-Page SEO API — Full Reference for AI Agents

> Source: https://api.on-page.ai/llms-full.txt
> Everything an AI agent or developer needs to understand and use the product
> in one file: what it does, endpoints, authentication, the report schema,
> pricing, rate limits, and how to connect the MCP server.

## What it is

On-Page.ai is an on-page SEO optimization API. You give it a URL and a target
keyword; it scans the page against the pages currently ranking on Google for
that keyword and returns a structured JSON report: an optimization score,
missing/weak entities, related-entity density vs the ranking cohort, topical
classification, internal-link candidates, competitor term coverage, structured-
data gaps, and (on deep scans) a page-experience speed benchmark.

It is built for applications and AI agents. Two ways to use it:
- REST API (asynchronous jobs) at https://api.on-page.ai
- MCP server at https://api.on-page.ai/mcp (HTTP Streamable transport)

It is NOT a rank-tracker, backlink index, or keyword-volume data provider. It
analyzes a specific page's on-page relevance against its live SERP competitors.

## How it works (asynchronous job model)

All analysis endpoints are async:
1. Submit a job (POST /v1/scan, /v1/scan/lite, /v1/scan/deep, or /v1/classify).
   The response returns a `job_id` and reserves credits.
2. Poll GET /v1/jobs/{job_id} for status/progress (free), or use the MCP
   `wait_for_job` helper.
3. Fetch GET /v1/jobs/{job_id}/result for the completed report (free).

Scans usually complete in ~30 seconds to 3 minutes depending on load.

## Authentication

- Send your key as a Bearer token: `Authorization: Bearer YOUR_API_KEY`
- API keys are organization-scoped. Jobs, credits, and rate limits are tracked
  per organization.
- Create and revoke keys in the dashboard at https://api.on-page.ai/dashboard/api-keys
  (the full key is shown once, at creation).
- Permission scopes: classify:create, scan:create, jobs:read, results:read,
  credits:read, webhooks:write.
- Errors: 401 INVALID_API_KEY (missing/invalid key); 403 ORGANIZATION_SUSPENDED.
- GET /v1/regions is public and needs no authentication.

Example (submit a standard scan, then fetch the result):

```
curl https://api.on-page.ai/v1/scan \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/","keyword":"your keyword","region":"US"}'
# -> { "job_id": "job_...", "status": "queued", "credits_reserved": 2 }

curl https://api.on-page.ai/v1/jobs/job_xxx/result \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Endpoints

Base URL: https://api.on-page.ai

| Method | Path | Cost | Description |
|---|---|---|---|
| POST | /v1/scan | 2 credits | Standard SEO scan against the top Google results for a keyword |
| POST | /v1/scan/lite | 1.5 credits | Quick scan — entity coverage + competitor cohort only |
| POST | /v1/scan/deep | 3 credits | Deep scan — 15 competitors + optional SERP-speed benchmark |
| POST | /v1/classify | 0.2 credits | Categorize a URL or raw text into 1,091 semantic categories |
| GET | /v1/jobs/{job_id} | Free | Poll job status and progress |
| GET | /v1/jobs/{job_id}/result | Free | Fetch the full report for a completed job |
| GET | /v1/credits | Free | Available and reserved credit balances |
| GET | /v1/regions | Free | List supported scan regions (public, no auth) |
| POST | /v1/webhooks/test | Free | Queue a test webhook delivery |

Scan request body (same for scan, scan/lite, scan/deep):
- `url` (string, max 2048 chars)
- `keyword` (string, whitespace-normalized, max 150 chars)
- `region` (ISO-3166 alpha-2, default "US")
- `locale` (BCP-47 language tag, max 16 chars)
- `compatibility_mode` (boolean, default false — slower browser rendering for
  difficult competitor pages)
- `market` is a deprecated alias for `region`.

Classify request body: provide at least one of `text` (max 20,000 chars) or
`url`; optional `languageHint`.

## Scan tiers

- Lite (1.5 credits): benchmarks, entities, highly-related words, and competitor
  cohort analysis. Skips page classification, internal-link recommendations,
  topical-authority questions, and structured-data sections.
- Standard (2 credits): the full audit, including structured-data benchmarks
  and coverage.
- Deep (3 credits): everything in Standard, plus 15 competitors and an optional
  self-hosted SERP-speed benchmark (LCP, CLS, approximate TBT, TTFB for your
  page vs the top 3 organic competitors). Speed metrics are measured in-house,
  not via Google PageSpeed/CrUX.
- Classify (0.2 credits): topical classification of a URL or raw text into
  1,091 categories.

## The scan report (schema: onpage-report-customer-v1)

A completed scan returns these top-level sections:

| Section | What it contains | Tiers |
|---|---|---|
| meta | Report date, target keyword, location, URL | all |
| on_page_optimization | Score, grade, confidence, summary, focus areas | all |
| benchmarks | Page-1 averages vs your page (content structure, entities) | all |
| entity_coverage | Entity/term coverage, related-entity density vs competitors, missing/weak entities, keyword variations | all |
| topic_and_classification | Page classification, swipe content, topical-authority questions | Standard, Deep |
| internal_linking | Source pages that should link to the analyzed URL | Standard, Deep |
| competitor_term_coverage | Term-by-term comparison vs ranking competitors | all |
| structured_data_benchmarks | Page-1 structured-data totals vs your page | Standard, Deep |
| structured_data_coverage | Schema.org type prevalence across the competitor cohort | Standard, Deep |
| serp_speed_benchmark | Page-experience benchmark vs top 3 organic competitors | Deep (optional) |

Lite scans use the schema `onpage-report-customer-v1-lite`. Both schemas are
published as MCP resources: `schema://customer-report-v1` and
`schema://customer-report-v1-lite`.

## Regions & locales

27 supported scan regions (Google SERP country). Default is US. `region`
selects the SERP country; `locale` controls result language. Supported codes:

US, CA, UK, AU, NZ, ES, DE, IT, FR, IE, NL, CH, SE, NO, DK, FI, ZA, MX, BR,
CO, IN, SG, MY, JP, KE, AE, HK.

Fetch the live list (with names and default locales) from GET /v1/regions.

## Rate limits & concurrency

Limits use a 60-second fixed window and apply per API key AND per organization;
exceeding either returns 429.

| Route type | Per key | Per org | Applies to |
|---|---|---|---|
| Read | 120/min | 360/min | /v1/jobs, /v1/credits |
| Create | 60/min | 180/min | /v1/classify |
| Scan | 20/min | 60/min | /v1/scan, /v1/scan/lite, /v1/scan/deep |

Per-organization job concurrency (classify + scan combined):
- 5 concurrent active jobs (over cap: 429 ORG_ACTIVE_LIMIT_REACHED)
- 100 max queued jobs (over cap: 429 ORG_QUEUED_LIMIT_REACHED)
- Rare global saturation: 429 SCAN_QUEUE_SATURATED

Response headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset
on authenticated responses; Retry-After, X-Concurrency-Limit,
X-Concurrency-Remaining on 429 responses. Higher throughput is available on
request via team@on-page.ai.

## MCP server (for AI agents)

- Server URL: https://api.on-page.ai/mcp
- Transport: HTTP (Streamable)
- Docs: https://api.on-page.ai/mcp/docs — Install: https://api.on-page.ai/mcp/install
- Connect by OAuth sign-in (ChatGPT Developer Mode, Claude Desktop custom
  connector) or with a Bearer MCP key from https://api.on-page.ai/dashboard/mcp.
- Supported clients include: Claude Code, OpenAI Codex, Cursor, VS Code
  (Copilot), Windsurf, Cline, ChatGPT, Claude Desktop, n8n — and any
  MCP-compatible client over HTTP.

Tools (8): classify_text, scan_page, scan_page_lite, scan_page_deep, check_job,
wait_for_job, get_job_result, check_credits.

Prompts (7): optimize_on_page_entities, internal_linking_plan,
optimize_subheadlines, authority_question_gap, competitor_gap_analysis,
serp_speed_comparison, content_brief.

Example (Claude Code):

```
claude mcp add --transport http --scope user on-page-seo \
  https://api.on-page.ai/mcp \
  --header "Authorization: Bearer YOUR_MCP_KEY"
```

## Pricing & plans

Pay-as-you-go credits. No subscriptions, no seats, no per-domain pricing.

- Free tier: 10 free credits on signup (about 5 standard scans). No credit card.
- Credit packs:
  - Starter — 200 credits — $99
  - Growth — 1,000 credits — $399 (most popular)
  - Agency — 5,000 credits — $1,799
  - Scale — 15,000 credits — $4,999 (best value)
- Custom top-up from $50 (auto-matches the nearest pack tier).
- Purchased credits are valid for 12 months from the grant date; signup credits
  effectively do not expire. Auto-refill earns +10% bonus credits.

Credit costs per action: classify 0.2, scan/lite 1.5, scan 2, scan/deep 3.
Polling job status, fetching results, checking credits, and listing regions
are free.

## Use cases (outcomes)

What you can achieve with the scan data, via the API or MCP. Each maps to a
scan plus an optional ready-to-run recipe at https://api.on-page.ai/automate-seo.

- Make a page rank higher on Google and in AI answers — optimize it against the
  pages currently winning the SERP, raising entity coverage and relevance.
- Find out why a page isn't ranking — pinpoint the relevance, entity-coverage,
  and structure gaps holding it back.
- Recover a page that lost its rankings — see what's missing and fix a stuck or
  declining page fast.
- Out-rank a specific competitor — surface what the ranking pages cover that
  yours doesn't, prioritized by impact.
- Close the content gaps on a page — add the high-value entities and topics the
  top results have and yours lacks.
- Optimize an entire site at scale — apply evidence-based fixes across every
  page without rewriting your content.
- Keep content fresh and stop ranking decay — refresh old and stale pages before
  they lose traffic.
- Strengthen rankings with internal links — add the internal links Google needs
  to understand and rank a page, on one page or site-wide.
- Win new clients and report progress — turn any prospect URL into a
  ready-to-send opportunity audit, and produce client-ready audit reports.
- Win local search — rank local pages across the cities and regions you serve,
  diagnose local ranking problems, align your site with your Google Business
  Profile, and stop local pages from cannibalizing each other.
- Show up in AI search — give ChatGPT, Claude, and other agents the structured
  evidence they need to recommend and cite your pages.

## Classification languages

Classification covers 1,091 semantic categories. English is the officially
supported language; French, Spanish, and German can be used but are unsupported
and results may vary.

## Key links

- Home: https://api.on-page.ai/
- Docs: https://api.on-page.ai/docs
- API reference: https://api.on-page.ai/docs/api
- Report schema: https://api.on-page.ai/docs/report-schema
- Pricing: https://api.on-page.ai/pricing
- MCP docs: https://api.on-page.ai/mcp/docs
- Curated index for agents: https://api.on-page.ai/llms.txt
- Contact: team@on-page.ai