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.

·4 min read

An SEO report API returns a report rather than a single check: scores for the site, a combined list of fixes, and a comparison with the previous run. You send a URL and a few options, and you get JSON that a dashboard, a client email or an AI agent can use without stitching together ten separate tool calls.

The hard part is not collecting checks. It is ordering the fixes. A report that lists 60 issues alphabetically is less useful than one that says which three to fix first.

What a report adds over a checker

A checker answers "what is wrong with this page". A report answers "what should we do next, and did it work".

Output What it is for
SEO readiness score A single number for a client or a release gate
AEO readiness score Whether the page is structured to be quoted by AI answers
AI access score Whether AI crawlers can fetch and read the site
Combined fix list One list ordered by priority, deduplicated across checks
Progress How many earlier issues are fixed, still present or new
Next step The single action the report recommends first

Scores without the fix list are decoration. The fix list without progress is a one-off audit. Buy the combination.

Call the assessment endpoint

Our report endpoint is POST /api/v1/assessments. It runs the selected check groups on the URL and up to two more pages on the same site.

curl -X POST https://seogeoaeo.ai/api/v1/assessments \
  -H "Authorization: Bearer $SEOGEOAEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "url": "https://example.com",
      "pages": ["https://example.com/pricing", "https://example.com/blog"],
      "brand": "Example"
    },
    "maxCredits": 114,
    "idempotencyKey": "example-weekly-2026-11-07"
  }'

The response is { "assessment": ... }. A one-page assessment costs 67 credits: 20 for the origin checks and 47 for the page checks. Each extra page adds 47. The default run covers robots, redirects and headers once, then indexing, on-page SEO, schema, readability, citability, freshness and author signals per page.

If status is in_progress, the first call hit its 40-second budget. Continue it with the same id:

curl -X POST https://seogeoaeo.ai/api/v1/assessments/{id}/continue \
  -H "Authorization: Bearer $SEOGEOAEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Performance and AI brand checks are slower. A performance check adds about two minutes and an AI brand description about three and a half, so allow a four-minute client timeout.

Choose the pages that matter

The report is only as good as the pages you feed it. Do not send the homepage three times.

  1. The homepage, for brand, organization schema and navigation.
  2. The page that earns the most organic clicks, from Search Console.
  3. The page that should earn money, usually pricing, a product page or a comparison page.

Two extra pages is the current limit. For a wider crawl, use the site-structure tools separately: the sitemap validator, the orphan page finder and the broken internal link finder.

Turn the JSON into a client report

The API returns data, not a PDF. That is deliberate: you decide the branding and the order. A readable report has five sections.

Section Content Source field
Summary One paragraph and the three scores scores
What changed Fixed, still present, new progress
Fix list Ordered actions with the page each applies to improvementTips
Evidence The checks that produced each fix the per-check results
Next step The one action to schedule next

Leave out every issue that does not change a decision. A client report with 60 rows gets skimmed. One with 8 gets read.

Schedule it and compare runs

A report becomes useful when it repeats. Run the same URL on the same day each week and store the assessment id.

  • Week 1 gives a baseline. Do not change anything until it finishes.
  • Week 2 shows which fixes landed. progress.percentFixed is the share of earlier issues now fixed.
  • Week 4 separates fixes that worked from fixes that were never shipped.
  • Quarterly gives a trend for the client and a reason to re-scope.

Use a cron job or your CI pipeline. Pass the same idempotencyKey only when retrying the same run; a new week needs a new key. A failed run is refunded, so a broken deploy does not burn credits.

What the report does not cover

  • Backlinks. The assessment reads the site, not the web. Use the backlink finder.
  • Rankings. Use Search Console or a rank tracker.
  • Competitors. Use the competitor finder and domain overview.
  • Legal and editorial judgment. The tool can flag a missing author, not whether the author is credible.

A report is a prioritization tool. It tells you where to spend the next week, not whether the business is worth investing in.

Generate one report before you automate it

Run one assessment in the browser, read the fix list and decide whether the order matches how you work. Our website assessment shows the same output with no setup. The agents page has the full REST reference, the MCP server and the skill file. If you only need a page check, SEO checker API is the smaller tool; if you need a template to fill, start from our SEO audit report template.

Related guidesFrom the same topic, then the newest guides.