SEO checker API: what it returns and how to call it

What an SEO checker API does, the fields a useful response returns, and how to run a page check over REST with authentication and a credit cap.

·4 min read

An SEO checker API is an HTTP endpoint that fetches a URL and returns structured findings about the page: its status, redirects, indexability, title, meta description, headings, canonical, structured data, images and links. You send a URL and get JSON back, so a script or an AI agent can run the same check a person would run in a browser, at the scale of a sitemap.

The useful distinction is between a checker and a data API. A checker reads the live page and reports what is wrong with it. A data API sells keyword, backlink or traffic estimates. Most SEO automation needs the first, and many teams buy the second by mistake.

What a useful response returns

A checker that only returns a score is hard to act on. Look for the evidence behind the score.

Field Why it matters
Final URL and redirect chain Shows whether the URL you checked is the URL Google sees
HTTP status and headers Catches a 404, a 5xx, a noindex header or a canonical header
Indexability Combines robots.txt, meta robots, X-Robots-Tag and canonical signals
Title and meta description The two fields that decide the search snippet
Headings Whether the page has one H1 and a readable outline
Canonical Whether the page points at itself or somewhere else
Structured data Which JSON-LD types are present and whether they parse
Images Missing alt text, oversized files and missing dimensions
Internal and external links Broken targets and nofollow attributes

If the response contains a list of issues, each issue should name the element, the value found and the fix. "Title is too long" is a score. "Title is 72 characters; Google truncates around 60" is a fix.

Call a checker over REST

Our API exposes each tool at POST /api/v1/tools/{slug}/runs. The body holds the tool input plus two optional controls: maxCredits refuses a run that would cost more than you allow, and idempotencyKey prevents a retry from charging twice.

curl -X POST https://seogeoaeo.ai/api/v1/tools/on-page-seo-checker/runs \
  -H "Authorization: Bearer $SEOGEOAEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": { "url": "https://example.com/pricing" },
    "maxCredits": 8,
    "idempotencyKey": "pricing-check-2026-11-07"
  }'

The response wraps the finished run in { "run": ... }. If the run is still queued or running, fetch it with GET /api/v1/runs/{id} and read status again. A failed run is refunded, so a timeout does not cost credits.

The same pattern works for every tool in the catalog. GET /api/v1/tools returns the slugs, input schemas and credit prices, and needs no key.

Pick the check that matches the question

Running every check on every URL wastes credits. These five cover most page-level work.

Tool slug What it checks Credits
indexing-checker Status, robots, noindex, canonical and whether the page can be indexed 8
on-page-seo-checker Title, meta description, headings, images and links 8
schema-checker JSON-LD types, required fields and parse errors 8
robots-checker The live robots.txt, blocked groups and AI crawler access 10
redirects-headers-checker Redirect chain, final URL and response headers 10

For a whole-site view, run the assessment endpoint instead of looping over pages. It runs the core checks on the origin and on up to two pages, then combines the fixes into one list.

Authentication, limits and cost

  • Key format. API keys start with sga_ and are shown once. Send one as Authorization: Bearer <key>. A workspace can hold 10 active keys.
  • Credits. Each run costs the same as the browser version. The on-page checker costs 8 credits per page.
  • Budget guard. maxCredits returns max_credits_exceeded instead of running. Set it to the price you expect.
  • Retries. Reuse the same idempotencyKey after a network error or timeout. The API returns the original run while it is still in the workspace's history.
  • Rate limits. A 429 includes Retry-After. Back off and retry rather than opening more connections.
  • Errors. Every error is { "error": { "code", "message" } }, so a script can branch on code without parsing prose.

When to use Google's APIs instead

Google's own APIs answer questions about properties you have verified, and they answer them with Google's data rather than a live fetch.

Need Use
Clicks, impressions and queries Search Console API
Index status of a URL you own URL Inspection API
Lab performance data PageSpeed Insights API
What any public URL returns right now A checker API
Keyword volume and CPC estimates A keyword data API

Most automation mixes them: pull the pages that lost clicks from Search Console, then run a checker on each one to see what changed.

Check one page before you check a thousand

Start with a single URL and read the full response before you write the loop. Our on-page SEO checker shows the same output in the browser, and the agents page documents the REST and MCP setup, including the skill file for Claude Code and other clients. If you need a scored report rather than a page check, read SEO report API next.

Related guidesFrom the same topic, then the newest guides.

  • Audits

    How to check all pages on a website

    How to find every page on a website, see which ones Google indexes, and spot the broken, thin and orphaned pages a sitemap never lists.

  • Audits

    SEO report API: one call, a full site report

    What an SEO report API returns beyond a single page check, how to generate a scored report with a fix list, and when to build the report yourself.

  • Audits

    6 best Screaming Frog alternatives in 2026

    The 6 best Screaming Frog alternatives in 2026, compared by price, crawl limits and where they run. Desktop and cloud crawlers, plus pay-per-run checks.