Keyword cannibalization report for competing URLs on your site.

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 returned queries surface more than one URL and deserve a closer intent review?

• Several pages appear to compete for the same search topic.
• A migration or template change may have split signals across URLs.

Command facts

Report id

cannibalisation

Execution

Local process

Outputs

JSON and Markdown

Example parameters

site, days, limit, minImpressions, includeBrand

Agent discovery

seo reports describe cannibalisation --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 relevant pages that could link to one chosen target URL rather than investigate several URLs shown for the same query. Recommended report: Find internal link candidates. Run internal links. It uses related Search Console query evidence and live link checks to find candidate source pages for the target.
• You need a final decision to merge, redirect, canonicalise, or keep the overlapping pages separate. No automated report can decide page intent, business value, or the preferred information architecture. Review the live pages, SERP intent, conversions, backlinks, and ownership of each topic. This report can still supply the overlap and first-party metrics for that review.

Data sources and inputs

• Returned Search Console query and page rows. Provides the URLs, query, clicks, impressions, CTR, and average position in the chosen period.
• Optional live-page verification. Adds current canonical, indexability, metadata, and content evidence for selected URLs.

What this report checks

• Groups returned rows by query and keeps only queries associated with more than one eligible URL.
• Ranks overlap consistently and separates observed exposure from heuristic intent or technical review signals.

How it works

• Aggregates duplicate provider rows, filters low-evidence groups, and ranks multi-URL exposure candidates with stable tie-breakers.

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

Review queries associated with more than one URL. Agents and CI should inspect the live schema before their first run.

seo cannibal --project example

seo reports describe cannibalisation --json

seo reports run cannibalisation --params '{"site":"sc-domain:example.com","days":90,"limit":20,"minImpressions":100,"includeBrand":false}' --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": "cannibalisation"
}

{
  "id": "cannibalisation",
  "params": {
    "site": "sc-domain:example.com",
    "days": 90,
    "limit": 20,
    "minImpressions": 100,
    "includeBrand": false
  }
}

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(
  'cannibalisation',
  {
  "site": "sc-domain:example.com",
  "days": 90,
  "limit": 20,
  "minImpressions": 100,
  "includeBrand": false
},
)

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

• Overlapping queries with their URLs, metrics, concentration, and the evidence behind the review priority.
• Optional page observations and cautious actions such as leave alone, inspect intent, review canonicals, or consider consolidation.
• Compare each URL’s purpose, canonical target, content, and search-result history. Query overlap is the observation; cannibalisation is a hypothesis to verify.

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

• Anonymised queries and returned row limits can hide additional URLs or make a group incomplete.

What to do next

1. Audit the competing URLs and decide whether to differentiate, consolidate, redirect, or leave them alone.
2. Measure any consolidation after a complete comparison window.

Related reports

• Audit one page. Inspect one live URL before changing its metadata, canonical, directives, structured data, links, or content.
• 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.
• Measure an SEO change. Compare equal, finalised search windows around a recorded change and see what moved without claiming the change caused it.

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 canonical URL guidance

Browse all reports in Search opportunities.