Page SEO opportunities report for one URL and its ranking queries.

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 query opportunities are associated with this page?

• A specific URL needs a compact opportunity view before deeper editing.
• You need the query evidence and page verification state together.

Command facts

Report id

page-opportunities

Execution

Local process

Outputs

JSON and Markdown

Example parameters

site, url, days, limit, minImpressions, verifyContent

Agent discovery

seo reports describe page-opportunities --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 detailed content brief for the selected page. Recommended report: Build a content optimization brief. Run content optimization for the URL. It combines its returned Search Console queries with the fetched title, headings, content, and technical conflicts to produce a reviewable brief.
• You suspect several URLs may be sharing the same query demand. Recommended report: Review query overlap and cannibalisation. Run cannibalisation across the property. It shows queries associated with multiple URLs so you can compare intent, canonicals, and live-page evidence before deciding whether the overlap is harmful.

Data sources and inputs

• Exact-page Search Console rows. Provides returned queries, clicks, impressions, CTR, and average position for the selected URL.
• Optional live-page fetch. Adds current metadata, content, and technical observations for a limited verification step.

What this report checks

• Filters and ranks returned query rows for the exact page and requested date range.
• Records whether page verification succeeded and keeps unverified content conclusions out of the result.

How it works

• Filters and ranks returned query rows for the target URL, records source completeness, and keeps unverified content conclusions out of the result.

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 the returned queries associated with one page. Agents and CI should inspect the live schema before their first run.

seo page-opportunities --project example --url https://example.com/page

seo reports describe page-opportunities --json

seo reports run page-opportunities --params '{"site":"sc-domain:example.com","url":"https://example.com/pricing","days":90,"limit":15,"minImpressions":40,"verifyContent":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.

{
  "id": "page-opportunities"
}

{
  "id": "page-opportunities",
  "params": {
    "site": "sc-domain:example.com",
    "url": "https://example.com/pricing",
    "days": 90,
    "limit": 15,
    "minImpressions": 40,
    "verifyContent": 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.

npm install seo

import { executeReport } from 'seo/mcp'

const result = await executeReport(
  'page-opportunities',
  {
  "site": "sc-domain:example.com",
  "url": "https://example.com/pricing",
  "days": 90,
  "limit": 15,
  "minImpressions": 40,
  "verifyContent": 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 compact query opportunity list with metrics, source completeness, and the selected page scope.
• Optional live-page observations plus investigation prompts that stay separate from measured search evidence.
• Read query metrics alongside verification and technical state. A high-impression row can still be the wrong intent for the page.

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 report only sees returned Search Console rows for the exact page scope and selected dates.

What to do next

1. Use content optimization when the page needs a fuller brief.
2. Use internal link candidates when discovery paths are the clearest supported gap.

Related reports

• Build a content optimization brief. Create a focused brief for one existing page from its own search queries and the content observed on the live URL.
• Find internal link candidates. Find fetched pages with relevant search evidence that do not currently contain a verified contextual link to a chosen target.
• Audit one page. Inspect one live URL before changing its metadata, canonical, directives, structured data, links, or content.

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 AI search evidence.