Redirect trace tool for SEO redirect chains and final URLs.

Use this before changing an old URL, debugging a migration, or checking where an important link lands. The report follows the chain and then inspects the final page it can reach.

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

Where does this URL end, how does it get there, and is the final destination technically coherent?

A migrated, shortened, or legacy URL behaves unexpectedly.
You need each hop rather than the final status alone.

Command facts

Report id: redirect-trace
Execution: Local process
Outputs: JSON and Markdown
Example parameters: url, maxHops, refresh
Agent discovery: seo reports describe redirect-trace --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 to find broken or unsuitable destinations across search-visible URLs, not trace one known URL. Recommended report: Recover broken URLs with search value. Run link recovery. It joins returned Search Console page metrics to fresh response and redirect evidence, then prioritises broken or poorly redirected URLs that still show search value.
You need to decide which destination is genuinely equivalent to the old page. No automated report can make that content and business decision. Compare the old purpose, user intent, content, and destination manually. Redirect trace can confirm how each candidate currently resolves, but it cannot prove topical equivalence.

Data sources and inputs

Live URL responses. Provides each status, location header, hop, final URL, and transport failure.
Final page evidence. Adds the final response, canonical, robots directives, title, and content type.

What this report checks

Follows redirects up to the explicit hop limit and records loops, invalid locations, failures, and the final destination.
Checks whether the final page is successful, indexable, and canonical to the intended URL based on observed evidence.

How it works

Follows redirects up to an explicit hop limit, detects loops and invalid locations, then audits the final response.

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

Follow every redirect hop to the final page. Agents and CI should inspect the live schema before their first run.

Run it from the CLI

seo redirect-trace --url https://example.com/old-page

Check the agent input schema

seo reports describe redirect-trace --json

Run it from an agent or script

seo reports run redirect-trace --params '{"url":"https://example.com/old-page","maxHops":8,"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.

Describe the report with MCP

{
  "id": "redirect-trace"
}

Run the report with MCP

{
  "id": "redirect-trace",
  "params": {
    "url": "https://example.com/old-page",
    "maxHops": 8,
    "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.

Install the library

npm install seo

Run this report from TypeScript

import { executeReport } from 'seo/mcp'

const result = await executeReport(
  'redirect-trace',
  {
  "url": "https://example.com/old-page",
  "maxHops": 8,
  "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

A hop-by-hop redirect chain with status codes, destinations, timing, and failure details.
Final-page extraction and focused findings for long chains, loops, broken endpoints, directives, and canonicals.
Prefer a short chain to the closest equivalent final page. Check that the final canonical and indexability match the intended move.

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

The trace describes this request from this environment. Geolocation, cookies, user agent, and JavaScript can produce other paths.

What to do next

Update internal links to the final destination.
Use link recovery to find other search-visible broken URLs.

Recover broken URLs with search value. Find URLs that still earn returned clicks or impressions but now fail, block access, or redirect poorly.
Audit one page. Inspect one live URL before changing its metadata, canonical, directives, structured data, links, or content.
Crawl a site for technical SEO issues. Map a limited part of a site, run the maintained technical checks, and save a reusable evidence baseline.

Sources behind the guidance

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

Browse all reports in Technical monitoring.