Skip to content

SEO checks

The SEO app checks every crawled page’s on-page fundamentals — the things an editor can fix from the CMS: titles, meta descriptions, canonicals, robots directives, headings, and structured data. It rides the same crawl as Broken Links (no extra requests, no separate metering) and refreshes on every crawl.

Install it with seoEnabled at registration (POST /v1/sites, default on) or later (PATCH /v1/sites/{id}). The report is served at GET /v1/sites/{id}/seo-report.

Rule Severity Fires when
title-missing serious the page has no (non-SVG) <title>
title-duplicate moderate two or more pages share the same title
title-too-long / title-too-short minor the title exceeds 60 characters / is under 10
title-multiple minor the page has more than one (non-SVG) <title>
meta-description-missing moderate no meta[name=description] with content
meta-description-duplicate moderate two or more pages share the same description
meta-description-length minor the description is under 50 or over 160 characters
canonical-missing minor no link[rel=canonical] and no canonical Link header
canonical-offsite serious the canonical points at a different site
canonical-mismatch moderate the canonical points at a different URL on the same site
canonical-conflict moderate the HTML canonical and the Link: <…>; rel="canonical" response header name different URLs
meta-noindex serious / critical a robots meta asks search engines to skip the page; critical when the page is in the sitemap (or is the root) — usually a publish gone wrong
x-robots-noindex serious / critical the X-Robots-Tag response header asks search engines to skip the page (unscoped, or scoped to googlebot/bingbot). Same severity logic as meta-noindex; invisible in the HTML, so usually a server, CDN or hosting setting
h1-missing / h1-multiple moderate / minor the page has no H1 / more than one
heading-order-skip minor the heading outline jumps more than one level down (e.g. H2 → H4); the first skip is reported
structured-data-invalid moderate a JSON-LD block doesn’t parse
structured-data-malformed moderate a property value is in a format search engines can’t read — a non-ISO date, a price with a currency symbol or comma decimal, a broken URL, or a block missing @context
structured-data-incomplete moderate a schema block of a catalogued type (Product, Article, FAQPage, BreadcrumbList, LocalBusiness, Organization, Event, JobPosting) is missing a property Google requires for rich results — e.g. a Product without offers or a price
og-image-missing minor the page has no og:image, so social and chat previews show no picture
internal-link-redirect minor the page links to URLs on the same site that redirect to a different page. The finding lists each link (anchor text, linked URL → destination), so editors can point it straight at the destination
content-duplicate moderate the page’s body text is identical to another indexable page’s (pages with at least 50 words; noindexed pages and pages whose canonical points elsewhere are skipped, unless more than 90% of the site is noindexed, as on a staging site)
content-thin minor an indexable page has fewer than 200 words of body text. Navigation, header, footer and scripts don’t count. Like content-duplicate, noindexed pages count when more than 90% of the site is noindexed
content-js-only moderate the HTML is an empty JavaScript app shell (an empty #root/#app/#__next/#__nuxt plus an entry script) with fewer than 50 words, so the content only appears once JavaScript runs. The page’s other results describe the shell
orphan-page moderate no link path from the homepage reaches the page — only the sitemap (or a page that is itself unreachable) points to it
deep-page minor the page is 5 or more clicks from the homepage along internal links
sitemap-missing minor an indexable page isn’t listed in the sitemap (only judged when the site has one)
sitemap-broken serious the sitemap lists a URL that answers with an error
sitemap-redirect minor the sitemap lists a URL that redirects to another page; the finding names the destination
sitemap-blocked moderate the sitemap lists a URL that robots.txt disallows for search engines (the Googlebot group, or *). Judged for them, not for Overwatch: a staging site that lets Overwatch in but keeps everyone else out still raises it

Site structure. The crawl keeps the links between your pages and walks them from the homepage, so it knows how many pages link to each page (byPage[].inlinks) and how many clicks away it is (byPage[].depth). It also compares the sitemap with what it found. summary.structure sums this up: pages per click depth, orphan and deep pages, and the sitemap counts. The link rules (orphan-page, deep-page) and sitemap-missing only run when the crawl finished below the site’s page limit. A crawl that stops early hasn’t seen every link, so they stay quiet rather than guess. A page that redirects counts as its destination, so links through a redirect still count. Noindexed pages and pages whose canonical points elsewhere are not judged on links or the sitemap.

Every rule in the report (byRule[].fix) and in the issues list (fix) carries a short how to fix line written for editors, next to help, which explains the finding.

Pages that answer with a bot-protection challenge instead of the page (a Cloudflare “Just a moment…” interstitial, a cf-mitigated: challenge header, or a 202 Accepted) are left out of the SEO snapshot for that run, so the interstitial can’t raise false findings. Allow the Overwatch user agent in your bot protection to have those pages checked.

Each crawl counts the pages it couldn’t read the way a visitor would. That is pages answered by a bot challenge, pages that refused access (401/403, or still rate-limited after every retry), and pages that were rate-limited at least once. The counts are stored on the run as pages_challenged, pages_blocked and pages_rate_limited. The SEO and AI readiness reports also return them as summary.crawlHealth, which is null when every page came through. When any count is above zero, the reports show a “results may be partial” notice.

JSON-LD presence (which pages carry structured data, which @type values, and which pages have none) is reported in the report’s structured-data panel as information, not as an issue. The required-property catalog is deliberately small and shallow — full schema.org validation is Google’s Rich Results Test’s job.

With Search Console connected, the report also shows Google’s own verdicts — soft 404s, failed fetches, ignored canonicals, rejected structured data and stale crawls — in the same bands, marked with a G. They don’t count towards the score.

Each run gets a 0–100 score: every rule is penalised by its severity and by how widely it spreads across the site, so a template-wide missing description counts as one systemic fix, not hundreds of independent hits. Only a completely clean run scores 100. The score’s methodology mirrors the accessibility score.

Separately, the indexability verdict answers the binary question “is anything actively blocking this site from being found?” — it flips to at-risk when a sitemap-listed page carries noindex, or a canonical credits another site.

Every finding has a stable identity across crawls: one issue per rule per page, with an id that doesn’t change between runs. When a crawl completes, each issue is reconciled against the previous state:

Transition When
new the rule fires on a page for the first time
open it fires again. Its detail/content follow the page (a too-long title that’s edited but still too long stays the same issue)
fixed the page was crawled and the rule no longer fires
gone the page is no longer reached by a complete crawl (deleted, unlinked, or excluded). Gone is reported separately and never counts as fixed
reopened a fixed issue fires again. An issue whose page merely came back after being gone reopens quietly, because nobody fixed it

A crawl that stops at the site’s page limit leaves issues on unvisited pages open: not checked isn’t fixed. Failed runs never change the lifecycle.

The first crawl after the lifecycle is introduced, and the first after the rule set changes (a new rule, a moved threshold), records a starting point: issues are tracked, but nothing counts as new and no alerts fire. That keeps a new rule from surfacing as hundreds of “new” issues overnight.

Resolved issues are kept for 180 days.

GET /v1/sites/{id}/seo-issues lists issues with their lifecycle, newest first. Its filters combine:

  • url=<page url> gives you the issues for one page. The URL is normalized the way the crawler keys pages (www folding, ignored query params), so you can pass a document’s public URL as-is.
  • new=true returns issues opened, or reopened after a fix, in the latest crawl.
  • status=open|resolved|all defaults to open. Resolved issues carry resolution: "fixed" | "page-gone".
  • changedIn=<runId> returns issues opened, reopened or resolved in that run.
  • rule=, severity=, plus limit (≤200) and cursor for pagination. Follow nextCursor until it’s null. A page can hold fewer than limit issues, because excludePaths globs are applied after paging.

The SEO report carries the same identity on every finding (issueId, firstSeenAt, isNew). Its summary.changes gives the latest crawl’s counts as { new, resolved, gone, reopened }. That field is null after a starting-point crawl. The per-run seo_new, seo_resolved, seo_gone and seo_reopened values are on GET /v1/sites/{id}/history.

When a page newly becomes blocked from search, Overwatch sends a seo.indexability_lost email and webhook to the site’s search-alert receivers (the same ones as search drops). A page is blocked when it’s in the sitemap (or is the root) and carries noindex, or when its canonical credits another site. Each page alerts once. It alerts again only if it’s fixed and then breaks again. See Notifications for the payload.

Issues are derived at read time from per-page field snapshots, so changing the site’s excludePaths globs immediately updates the report (and duplicate detection recomputes over the remaining pages). The score stored on each run feeds the trend chart and is refreshed when the globs change.

Toggling the app off stops the extraction and makes the report respond 404; past runs’ snapshots are kept, so the report returns when the app is re-installed. If SEO is the only crawl-consuming app on the site, turning it off also unschedules the crawl — see Apps.