Report Schema

The scan report is a structured JSON document organized for action. Understand what each section means so you can turn the data into specific SEO improvements.

Report sections

Standard and Deep customer_v1 reports share the core sections below; the serp_speed_benchmark row is Deep-only and optional (present when the benchmark produced a payload). The schema_version field is always onpage-report-customer-v1.

meta

Report date, target keyword, location, and URL.

report_datetarget_keywordlocationurl

on_page_optimization

Final On-Page Optimization Score, grade, numeric confidence, summary, and high-level focus areas.

scoregradeconfidencesummaryfocus_areas

benchmarks

Page-1 averages vs your page, side by side.

page1_averageyour_url

entity_coverage

Entity and term coverage, including related-entity density versus competitors — the core of most optimization work.

your_url_related_entity_density_scorecompetitor_related_entity_density_scorenatural_language_entitieshighly_related_termskeyword_variationsrelated_category_entitiesspecific_category_entities

topic_and_classification

Topic classification, swipe content, and authority questions.

page_classificationswipe_contenttopical_authority_questions

internal_linking

Source pages that should link to the analyzed URL.

add_internal_links_fromto_your_url

competitor_term_coverage

Term-by-term comparison against ranking competitors.

domainsterms

serp_speed_benchmark

Deep scans only. Self-hosted page-experience benchmark of the target URL against the top 3 organic competitor URLs in the same SERP. Optional — Deep responses include the field when the benchmark payload was produced; when present, `status` indicates whether the run completed (`ok`) or was short-circuited (`disabled`, `skipped_*`, `timeout`). Lite and Standard never include it.

statuswhat_this_measuresmeasurement_typedevice_profilenetwork_profilecpu_profilebenchmark_versionweb_vitals_versiontargetcompetitors

How to use the report for SEO

The report is most useful as a prioritization engine. Don't try to act on everything at once — focus on the highest-impact gaps first.

Optimization score — start with the benchmark

on_page_optimization gives the final score, numeric confidence, and focus areas for the page. Use it as the top-level benchmark before drilling into the supporting sections.

Entity coverage — find missing topics

Look at natural_language_entities with coverage_status of "missing". Start with the highest-importance terms. Edit existing sentences to include them rather than adding new paragraphs.

Related entity density — judge depth, not just presence

Compare your_url_related_entity_density_score with competitor_related_entity_density_score to see whether important related entities appear with enough depth for the page length.

Authority questions — close topical gaps

The who/what/where/how questions show what angles your page should address. Add the ones that fit your page intent — don't force irrelevant angles.

Internal linking — strengthen your page

add_internal_links_from gives you specific source pages and anchor text suggestions. These are pages on YOUR site that should link to the analyzed page.

Competitor coverage — benchmark yourself

Compare domains and terms to see which topics the top-ranking pages all cover that you don't. Patterns across multiple competitors are stronger signals than individual outliers.

Benchmarks — quantify the gap

page1_average vs your_url gives you numerical scores across the same metrics. Use this to prioritize which metrics have the largest gaps.

SERP speed (Deep only) — compare page experience

serp_speed_benchmark.target vs serp_speed_benchmark.competitors shows LCP, CLS, approximate TBT, and TTFB side-by-side with the top 3 organic competitors in the same SERP (FCP is captured at the per-probe level too). Recommend page-experience fixes only where the target is materially worse than the competitor median — skip ties and per-probe statuses other than `ok`.

Legacy field mapping

If you're migrating from the older report format, here's how the section names map to the current schema.

Legacy name	Current path
Date / TargetKeyword / Location / URL	`meta`
OnPageOptimizationScore	`on_page_optimization`
Page1AverageVsYourUrl	`benchmarks`
NaturalLanguageAnalysis	`entity_coverage.natural_language_entities`
HighlyRelatedWords	`entity_coverage.highly_related_terms`
KeywordVariations	`entity_coverage.keyword_variations`
RelatedCategory	`entity_coverage.related_category_entities`
SpecificCategoryEntities	`entity_coverage.specific_category_entities`
PageClassification	`topic_and_classification.page_classification`
SwipeContent	`topic_and_classification.swipe_content`
TopicalAuthorityQuestions	`topic_and_classification.topical_authority_questions`
Internal Link Recommendations	`internal_linking`
CompetitorAnalysis	`competitor_term_coverage`

Machine-readable schemas

Two JSON Schemas are published as MCP resources, one per tier:

schema://customer-report-v1 — full shape for Standard and Deep scans (response_format=customer_v1). Carries benchmarks, entity coverage including related-entity density, topic and classification, internal linking, and competitor term coverage.
schema://customer-report-v1-lite — reduced shape for Lite scans (response_format=customer_v1_lite). Keeps benchmarks, entity coverage including related-entity density (natural language entities, highly related terms, keyword variations only), and competitor term coverage. Omits topic_and_classification and internal_linking entirely — those are not computed for Lite scans.

The service picks the right schema automatically based on the job's depth. Explicitly requesting customer_v1 on a Lite job (or customer_v1_lite on a Standard/Deep job) returns a 409 UNSUPPORTED_FORMAT — omit the parameter or use the matching value.