Broken link recovery for SEO pages that still have search value.

Run this report from the CLI, an MCP client, or application code. Every surface uses the same report definition and returns the same evidence. JSON is the source of truth; Markdown makes it readable without hiding dates, limits, warnings, or skipped work.

What this report helps you decide

Which search-visible URLs now lead users and crawlers to a broken or unsuitable destination?

• A migration, deletion, or release may have stranded valuable URLs.
• Search Console evidence should determine which URLs get checked first.

Command facts

Report id

link-recovery

Execution

Local process

Outputs

JSON and Markdown

Example parameters

site, days, limit, minClicks, minImpressions, refresh

Agent discovery

seo reports describe link-recovery --json

Interactive prompts

Human CLI commands only

When this report is not the right tool

These cases need a different report, more evidence, or a human decision. Do not force this report to answer a question its data cannot support.

• You need every redirect hop and the final page controls for one recovery candidate. Recommended report: Trace a redirect chain. Run redirect trace for that URL. It adds the complete hop sequence plus the final response, canonical, robots directives, and indexability evidence needed to verify a redirect fix.
• You need to decide whether an old URL should be restored, redirected, or left gone. No automated report can decide relevance, replacement quality, or business intent. Use this report to rank URLs with observed search value, then review the old purpose and the best current destination before choosing a response.

Data sources and inputs

• Returned Search Console page evidence. Provides clicks and impressions for URLs that still hold observed search value.
• Live response and redirect evidence. Shows whether each candidate fails, blocks access, redirects poorly, or reaches a usable final page.

What this report checks

• Finds search-visible URLs and verifies their current response, redirect chain, access, indexability, and final destination.
• Ranks supported recovery candidates by returned value and observed technical state without assuming every old URL should return.

How it works

• Ranks eligible search-value URLs, fetches a limited set, traces outcomes, and keeps failed verification separate.

The JSON result keeps dates, thresholds, limits, skipped work, and source completeness beside the finding. Missing, partial, capped, filtered, and complete data remain different states.

Run the report from the CLI

Find broken or poorly redirected URLs with returned search value. Agents and CI should inspect the live schema before their first run.

seo link-recover --project example

seo reports describe link-recovery --json

seo reports run link-recovery --params '{"site":"sc-domain:example.com","days":90,"limit":25,"minClicks":1,"minImpressions":100,"refresh":true}' --json

Project profiles can fill supported property and analytics inputs for the human-facing commands. The catalog form shown here is explicit by design, so agents and CI jobs do not prompt or guess.

How an MCP agent should use it

Call seo_describe_report first so the agent sees when this report is useful and gets the current input schema. Then callseo_run_report with the validated parameters. Read the status, warnings, source limits, and skipped sections before acting on a finding.

{
  "id": "link-recovery"
}

{
  "id": "link-recovery",
  "params": {
    "site": "sc-domain:example.com",
    "days": 90,
    "limit": 25,
    "minClicks": 1,
    "minImpressions": 100,
    "refresh": true
  }
}

Use a follow-up report returned by the result instead of guessing the next tool. The local MCP server and CLI use the same report definition and evidence. Their outer transport envelopes differ.

Use the report in a TypeScript app

Install seo as a project dependency, then call the same report catalog used by the CLI and MCP. executeReportrejects an unknown report id or invalid parameters. Provider and runtime failures come back as structured results withisError set.

npm install seo

import { executeReport } from 'seo/mcp'

const result = await executeReport(
  'link-recovery',
  {
  "site": "sc-domain:example.com",
  "days": 90,
  "limit": 25,
  "minClicks": 1,
  "minImpressions": 100,
  "refresh": true
},
)

console.log(result)

The TypeScript library guide also covers direct core functions, schema discovery, and the difference betweenexecuteReport and runReport.

What comes back and how to read it

• Broken, blocked, or poorly redirected URLs with returned clicks, impressions, live status, and final destination evidence.
• A limited recovery queue with restore, redirect, canonical, investigate, or leave-alone guidance tied to observed evidence.
• Restore a useful page or redirect to the closest genuinely equivalent destination. A 200 response alone does not make the destination appropriate.

Start with dataStatus, source details, warnings, and caveats. Then inspect the observed evidence before derived findings or suggested actions.

What this report cannot tell you

• Returned Search Console rows are not a complete historical URL inventory, and fetched behavior can differ by user agent.

What to do next

1. Trace the specific redirect chain.
2. Recrawl and monitor the repaired URL.

Related reports

• Trace a redirect chain. Follow every hop from one URL to its final page and catch loops, long chains, broken destinations, or conflicting index signals.
• Monitor crawl changes. Crawl the same limited URL scope again and find technical or page changes since the previous monitoring run.
• Review Google index changes. Inspect a limited URL set and separate current index issues, regressions, recoveries, and operational failures.

Sources behind the guidance

These primary sources define the provider data or search controls used in the interpretation above.

• Search Console Search Analytics API guidance
• Google guidance for redirects
• Google canonical URL guidance

Browse all reports in Technical monitoring.