Find the URLs behind your technical SEO issues

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 crawled URLs are affected by this rule, category, or severity?

• A crawl summary has identified a pattern and you need the limited URL inventory.
• An agent needs evidence for a targeted follow-up rather than the whole crawl payload.

Command facts

Report id

affected-urls

Execution

Local process

Outputs

JSON and Markdown

Example parameters

reportId, ruleId, severity, limit

Agent discovery

seo reports describe affected-urls --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 know several crawl issues exist but need to decide which ones deserve attention first. Recommended report: Fix the most important technical SEO issues. Run top fixes. It compares issue severity, affected-page counts, and available search or analytics value so you get a ranked work list rather than the URLs for one chosen issue.
• You do not yet understand what a crawler rule means or whether its suggested fix applies to your site. Recommended report: Understand a crawler issue. Explain the crawl issue first. It adds the maintained rule meaning, rationale, fix, and verification method. Then return here when you are ready to inspect the real affected URLs.

Data sources and inputs

• Saved or fresh crawl findings. Provides issue instances, rule ids, affected pages, severity, and technical evidence.
• Optional rule, category, and severity filters. Narrows the result to the finding you are ready to inspect.

What this report checks

• Matches crawl issue instances against the requested rule, category, or severity.
• Orders URLs by severity and available clicks, impressions, and sessions before applying the explicit limit.

How it works

• Filters the report by explicit rule, category, or severity and returns a stable limited URL list.

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

This report currently uses the shared report runner in the CLI. Agents and CI should inspect the live schema before their first run.

seo reports describe affected-urls --json

seo reports run affected-urls --params '{"reportId":"crawl_example_20260710","ruleId":"missing_title","severity":"high","limit":50}' --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": "affected-urls"
}

{
  "id": "affected-urls",
  "params": {
    "reportId": "crawl_example_20260710",
    "ruleId": "missing_title",
    "severity": "high",
    "limit": 50
  }
}

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(
  'affected-urls',
  {
  "reportId": "crawl_example_20260710",
  "ruleId": "missing_title",
  "severity": "high",
  "limit": 50
},
)

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

• Affected URLs with rule id, severity, detail, evidence, and available Search Console or GA4 metrics.
• Selection metadata showing total matches, returned rows, limit, and whether the list was truncated.
• Confirm the rule meaning and page intent before bulk changes. Repeated URLs can reveal a template problem, but the report does not prove one shared cause.

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 result is limited by the original crawl and the requested output limit.

What to do next

1. Use explain issue for the rule guidance.
2. Audit representative URLs and recrawl after the fix.

Related reports

• Understand a crawler issue. Turn one crawler rule id into plain-English meaning, practical fixes, impact context, and a repeatable verification step.
• Audit one page. Inspect one live URL before changing its metadata, canonical, directives, structured data, links, or content.
• Compare two saved crawls. See which pages and technical issues appeared, disappeared, or changed between two saved crawl snapshots.

Browse all reports in Crawling and technical checks.