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 asAuthorization: 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.
maxCreditsreturnsmax_credits_exceededinstead of running. Set it to the price you expect. - Retries. Reuse the same
idempotencyKeyafter a network error or timeout. The API returns the original run while it is still in the workspace's history. - Rate limits. A
429includesRetry-After. Back off and retry rather than opening more connections. - Errors. Every error is
{ "error": { "code", "message" } }, so a script can branch oncodewithout 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.





