Search query clustering report for repeated GSC demand themes.

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 query rows share enough wording to review as a topic group?

• You need compact themes for research, page review, or reporting.
• A repeatable lexical grouping is more useful than a model-generated label.

Command facts

Report id

query-clusters

Execution

Local process

Outputs

JSON and Markdown

Example parameters

site, scope, minImpressions, limit, includeBrand

Agent discovery

seo reports describe query-clusters --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 to understand the opportunities and live content for one page rather than group query wording. Recommended report: Find opportunities for one page. Run page opportunities for the URL. It adds exact-page Search Console rows and optional live-page verification instead of grouping property-wide query text.
• You need a final information architecture or a definitive judgment that grouped queries share the same search intent. No automated report can settle intent from token overlap alone. Review the cluster members, current search results, existing pages, and user task manually; use these repeatable groups to reduce the query set you need to inspect.

Data sources and inputs

• Returned Search Console queries. Provides query wording and metrics from the selected property and date range.
• Clustering threshold and limits. Control the required token overlap, source rows, and number of groups returned.

What this report checks

• Normalises eligible query tokens and groups rows using the documented overlap threshold.
• Aggregates returned metrics and orders clusters consistently while preserving source limits.

How it works

• Normalizes query tokens, applies a documented overlap rule, aggregates metrics, and uses stable ordering.

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

Group returned Search Console queries into repeatable themes. Agents and CI should inspect the live schema before their first run.

seo query-cluster --project example

seo reports describe query-clusters --json

seo reports run query-clusters --params '{"site":"sc-domain:example.com","scope":"/guides/","minImpressions":50,"limit":20,"includeBrand":false}' --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": "query-clusters"
}

{
  "id": "query-clusters",
  "params": {
    "site": "sc-domain:example.com",
    "scope": "/guides/",
    "minImpressions": 50,
    "limit": 20,
    "includeBrand": false
  }
}

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(
  'query-clusters',
  {
  "site": "sc-domain:example.com",
  "scope": "/guides/",
  "minImpressions": 50,
  "limit": 20,
  "includeBrand": false
},
)

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

• Named query groups with member queries, aggregate metrics, representative terms, and stable ordering.
• Selection and source metadata showing returned rows, limits, filtering, and possible truncation.
• Use clusters to reduce a review set. Read representative queries before assigning intent or deciding that one page should cover the group.

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

• Token overlap misses synonyms and can join phrases whose meaning differs. Anonymised queries are absent.

What to do next

1. Inspect the pages receiving impressions for each useful cluster.
2. Run query overlap when several URLs appear for the same group.

Related reports

• Review query overlap and cannibalisation. Find queries associated with several URLs and separate healthy search coverage from genuine intent, canonical, or consolidation problems.
• Find opportunities for one page. See which returned search queries are already associated with one URL and what deserves a closer look on the live page.
• 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.

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 Search opportunities.