Keyword opportunity report

Build one bounded research queue from searches already associated with the site. Add independent market estimates only when they would change the next investigation, since external acquisition can cost money.

Install and run the report

Install the CLI once, then run seo start to connect your site and Google data. After setup you can run this report yourself or ask your agent to run it.

Runafter install

Install the SEO CLI globally.

npm i -g seo

Run setup after installation.

seo start

Build a first-party opportunity queue without making a paid provider request.

seo reports run keyword-opportunities --params '{"site":"sc-domain:example.com","days":90}' --json

What you get from this report

Build one bounded queue from existing Search Console opportunities, then optionally add market estimates without changing the first-party priority scores.

Best for: You want one bounded review queue across quick wins, second-page queries, and striking-distance evidence.
Needs: Search Console property and date range
You get: Separate first-party, external, and combined evidence with source coverage, limits, request cost, cache status, warnings, and caveats.
Use next: Compare keyword metrics

What you need before you run it

This report uses one bounded Search Console query and page acquisition, three existing opportunity analyses, and optional provider estimates for an explicit market.

Search Console property and date range

Returns retained query and page rows for the selected property and finalised date window.

Opportunity and output limits

Bound quick-win, second-page, striking-distance, keyword, URL, cluster, and structured output sizes.

Optional external market

Adds provider estimates only when includeExternal is true and a country and language are supplied. This can make a paid request.

How the report finds the opportunity

The report uses existing search and page evidence to build a limited review list. An opportunity is a reason to inspect a page, not a promise of more traffic.

Runs quick-win, second-page, and striking-distance analysis from one bounded Search Console acquisition instead of fetching the same source three times.

Selects unique keywords across all three sections, keeps provider value states and cost visible, and does not blend external estimates into first-party scores.

Groups only the selected opportunity subset and flags repeated URL patterns for representative template and data-source review.

Check the evidence behind each opportunity

Start with the query, page and date range behind each suggestion. Thin or partial evidence belongs in the review pile, not the implementation queue.

Read first	Why it matters
Result	Separate first-party, external, and combined evidence with source coverage, limits, request cost, cache status, warnings, and caveats.
More detail	A bounded keyword queue, query clusters, programmatic patterns, evidence-linked findings, and up to three data-source validation prompts.
Read it with	Start with first-party impressions, pages, average position, and source sections. Use external volume or trend only as added context, then inspect the current result before choosing a target.

What the result cannot prove

Search Console omits anonymised queries and average position is not an exact rank. External metrics are estimates, and external acquisition may cost money when explicitly enabled. Clusters and URL patterns use a selected subset. They can identify a useful programmatic SEO investigation, but cannot prove that more pages should exist.

Start with first-party impressions, pages, average position, and source sections. Use external volume or trend only as added context, then inspect the current result before choosing a target. Run the programmatic SEO audit for a repeated template cluster before expanding it.

Use a different report for these jobs

You need an exact rank, a current result snapshot, or a verified competitor list. You want external metrics to replace Search Console evidence or automatically change first-party priorities.

You already have a keyword list and only need independent market estimates.

Run keyword metrics with the exact terms, country, language, location, and device you need. It skips Search Console opportunity selection and reports provider evidence directly.

Keyword metrics report

A repeated URL pattern needs representative page and template evidence.

Run the programmatic SEO audit for the chosen scope. It reviews template population, samples, crawl findings, Search Console evidence, and optional inspection verdicts before you change the generator.

Programmatic SEO audit

You need exact rankings, current competitors, or result-page intent.

Collect a current result snapshot for the same query, country, language, location, and device. This report contains average Search Console position and optional market estimates, not a live result page.

Needs more evidence

Use the report with an agent or in code

The command above is enough for most work. These options let an agent, script or application run the same report with explicit input and structured output.

Use the report catalog when an agent, script or CI job needs predictable JSON instead of the normal terminal output. Check the current input first, then run the report with the validated parameters.

Check the current input before the agent or script runs the report.

seo reports describe keyword-opportunities --json

Once the input is valid, run the report through the report catalog.

seo reports run keyword-opportunities --params '{"site":"sc-domain:example.com","days":90,"limit":10,"keywordLimit":30,"includeExternal":false}' --json

An MCP agent follows the same two-step flow. It inspects the current schema, fills the required fields and only then runs the report.

Ask the MCP server for the current report input.

{
  "id": "keyword-opportunities"
}

Run the report after the agent has checked and filled the input.

{
  "id": "keyword-opportunities",
  "params": {
    "site": "sc-domain:example.com",
    "days": 90,
    "limit": 10,
    "keywordLimit": 30,
    "includeExternal": false
  }
}

Install the package in a Node 22 project when your application needs to run the report directly. The result includes the same evidence, warnings and limits returned through the CLI and MCP server.

Add the SEO package to your project.

npm install seo

Run the report from your TypeScript application.

import { executeReport } from 'seo/mcp'

const result = await executeReport(
  'keyword-opportunities',
  {
  "site": "sc-domain:example.com",
  "days": 90,
  "limit": 10,
  "keywordLimit": 30,
  "includeExternal": false
},
)

console.log(result)

What to do next

Start with the Search Console evidence and the report section that supplied each candidate. Use provider estimates as added context, inspect the current results, and audit representative pages before creating content or expanding a template.

01Audit the strongest existing page and inspect a current result snapshot for its query and market.
02Run the programmatic SEO audit for a repeated template cluster before expanding it.

Check a limited keyword set against independent market estimates while keeping missing fields, provider coverage, cache status, and local request cost visible.

Keyword metrics report

Review repeated page families with search demand, limited crawl samples, and optional Google index evidence kept separate.

Programmatic SEO audit

Turn a large returned Search Console query set into reproducible groups that are easier to review for shared demand.

Search query clustering report

Inspect one live URL before changing its metadata, canonical, directives, structured data, links, or content.

SEO page audit

Sources used by this report

These primary sources define the provider data or search controls used by the result.