Internal linking SEO report for stronger target pages.

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 existing pages may be useful, natural places to link to this target URL?

• A sound target page needs better discovery paths or supporting context.
• You want a review queue rather than automatic anchor insertion.

Command facts

Report id

internal-links

Execution

Local process

Outputs

JSON and Markdown

Example parameters

site, targetUrl, days, limit, checkLimit, minImpressions

Agent discovery

seo reports describe internal-links --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 a page brief for the target rather than possible source pages. Recommended report: Build a content optimization brief. Run content optimization for the target URL. It adds the live page structure and its returned Search Console queries so you can review topic coverage before adding links.
• You need the final anchor text and exact sentence where a link should appear. No automated report can choose natural wording without editorial context. Use these candidates to open the source and target pages, then place a descriptive link only where it helps the reader and matches the surrounding copy.

Data sources and inputs

• Search Console page and query evidence. Finds pages with returned query wording related to the chosen target topic.
• Fetched source and target pages. Verifies current links, page availability, canonical state, and visible content context.

What this report checks

• Finds returned query overlap between the target topic and eligible source pages.
• Fetches limited candidates and keeps only pages where no contextual link to the canonical target was verified.

How it works

• Ranks exact and lexical relevance, fetches a limited candidate set, excludes unsuitable pages, then verifies whether a contextual link exists.

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 fetched pages that may deserve a link to the target. Agents and CI should inspect the live schema before their first run.

seo internal-links --project example --url https://example.com/page

seo reports describe internal-links --json

seo reports run internal-links --params '{"site":"sc-domain:example.com","targetUrl":"https://example.com/guides/seo","days":90,"limit":15,"checkLimit":40,"minImpressions":25}' --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": "internal-links"
}

{
  "id": "internal-links",
  "params": {
    "site": "sc-domain:example.com",
    "targetUrl": "https://example.com/guides/seo",
    "days": 90,
    "limit": 15,
    "checkLimit": 40,
    "minImpressions": 25
  }
}

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(
  'internal-links',
  {
  "site": "sc-domain:example.com",
  "targetUrl": "https://example.com/guides/seo",
  "days": 90,
  "limit": 15,
  "checkLimit": 40,
  "minImpressions": 25
},
)

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

• Ranked source-page candidates with supporting queries, metrics, current link state, and target URL.
• Verification status, failed fetches, limits, caveats, and a prompt to choose natural anchor and placement manually.
• Read the source passage. Add a link only when the target genuinely helps at that point, using anchor text that makes sense to a reader.

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

• Unchecked candidates remain unknown when the fetch limit is reached. A relevance score is not an impact forecast.

What to do next

1. Add one useful contextual link and recrawl the source page.
2. Use audit page to verify the target remains indexable and canonical as intended.

Related reports

• 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.
• 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 guidance for crawlable links

Browse all reports in Search opportunities.