SEO segment impact report for Search Console movement.

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 part of the property accounts for the observed search-performance change?

• A property-level rise or fall needs to be broken down by page or query.
• You need winners, losers, and unmatched rows in one comparison.

Command facts

Report id

segment-impact

Execution

Local process

Outputs

JSON and Markdown

Example parameters

site, dimension, days, compareDays, limit, maxRows, unmatchedLimit

Agent discovery

seo reports describe segment-impact --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 do not yet know which dimension or focused investigation to start with. Recommended report: Review SEO performance. Run the search performance overview. It checks the strongest available movements across pages, queries, countries, and devices, then points to the focused report supported by the returned evidence.
• You need to prove why one segment gained or lost traffic. No automated report can isolate the cause from Search Console movement alone. Check releases, tracking, seasonality, demand, search-result changes, and representative pages. Segment impact can identify where to investigate and provide the matched dates and rows.

Data sources and inputs

• Matched Search Console periods. Provides returned rows for the chosen page, query, country, or device dimension.
• Dimension and row limits. Define which segment to compare and how many matched or unmatched rows to retain.

What this report checks

• Builds adjacent equal-length finalised periods for the selected dimension.
• Compares clicks, impressions, CTR, and average position for the chosen segment.
• Aggregates duplicates consistently and separates matched, new-only, missing-only, partial, and truncated rows.

How it works

• Aggregates duplicate rows consistently, compares like-for-like returned segments, and does not treat a missing segment as zero.

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

Compare matched periods by page, query, country, or device. Agents and CI should inspect the live schema before their first run.

seo segment-impact --project example

seo reports describe segment-impact --json

seo reports run segment-impact --params '{"site":"sc-domain:example.com","dimension":"page","days":28,"compareDays":28,"limit":20,"maxRows":50000,"unmatchedLimit":10}' --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": "segment-impact"
}

{
  "id": "segment-impact",
  "params": {
    "site": "sc-domain:example.com",
    "dimension": "page",
    "days": 28,
    "compareDays": 28,
    "limit": 20,
    "maxRows": 50000,
    "unmatchedLimit": 10
  }
}

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(
  'segment-impact',
  {
  "site": "sc-domain:example.com",
  "dimension": "page",
  "days": 28,
  "compareDays": 28,
  "limit": 20,
  "maxRows": 50000,
  "unmatchedLimit": 10
},
)

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

• Largest supported gains and declines with clicks, impressions, CTR, position, and absolute movement.
• Separate unmatched-row evidence, source completeness, limits, warnings, and a verdict for the selected segment.
• Separate matched changes from rows seen in only one window. Large unmatched sets or capped sources weaken property-wide conclusions.

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

• Search Console row retention and anonymised queries mean the returned dimensions may not reconcile to property totals.

What to do next

1. Audit the pages behind the largest supported changes.
2. Run traffic anomaly or update correlation when timing still needs context.

Related reports

• Investigate an organic traffic drop. Compare recent Search Console clicks and impressions with the site history to find unusual changes.
• Audit one page. Inspect one live URL before changing its metadata, canonical, directives, structured data, links, or content.
• Check traffic changes against Google updates. Place unusual Search Console movement beside confirmed Google ranking update windows without claiming the update 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

Browse all reports in Property diagnosis.