gsc_breakdown
A SNAPSHOT-ONLY breakdown of Google Search Console metrics (clicks / impressions / CTR / average position) DOWN BY a drill field — category, country, device, intent (a customer keyword group), query, page, rank bucket, traffic source, language or geo — with the full curated filter set and optional snapshot period-over-period. Use only for ONE summarized range such as "top pages by clicks" or "clicks by country". NEVER call this tool when the user asks for a day/week/month/quarter series by a drill field, including a comparison or top-N series; call gsc_dimensional_trend exactly ONCE with all requested metrics and put the second explicit period in comparison_range. For a single whole-site or top-N snapshot WITHOUT a break-by field, use search_performance; for biggest movers use seo_ranking_movement_report; for share vs competitors use the market-share analyses.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"date_range": "<date_range>",
"group_by": "<group_by>"
},
"name": "gsc_breakdown"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| brand | No | Convenience: restrict to branded ("Yes") or non-branded ("No") demand (mapped into filters). | |
| top_n | No | How many top rows to return. | |
| intent | No | Convenience: restrict to one intent (a customer keyword group); mapped into filters. Resolve the id with resolve_entity first. | |
| medium | No | Source medium. DEFAULTS to "google/organic" — organic Search Console metrics. Pass "google/cpc" for paid. | |
| source | No | Where Google search performance data is read from. Use "bigquery" ONLY when the user explicitly asks for BigQuery as the source AND describe_data_sources reports it available from live customer configuration — it returns far more granular per-query data (privacy-suppressed impressions appear under "[anonymized by google]"). | default |
| filters | No | Curated GSC filters with operators (matches the UI). e.g. country in usa,can: [{field:"country",op:"eq",value:["usa","can"]}]; page contains "/blog/": [{field:"page",op:"contains",value:"/blog/"}]; non-brand: [{field:"brand",op:"eq",value:"No"}]. regex/not_regex only on query/page. | |
| metrics | No | Which metrics to return; defaults to clicks + impressions. | |
| sort_by | No | Which metric to rank the rows by; defaults to the first requested metric. | |
| group_by | Yes | REQUIRED — the field to break the metrics down by, e.g. "category", "country", "device", "intent", "query", "page", "rank_bucket", "traffic_source", "language", or a keyword/page geo field. | |
| date_range | Yes | Explicit date range, e.g. "2026-05-01 to 2026-05-31". Both endpoints are INCLUSIVE — the END day is covered (a 7-day range = 7 days). Quattr weeks run Sunday–Saturday; for "last week" use the most recent complete Sun–Sat span. | |
| granularity | No | Backward-compatible handler input only. Clients MUST NOT select gsc_breakdown for a day/week/month/quarter series. Call gsc_dimensional_trend exactly once for the full primary range, include every requested metric, and put any explicit second period in comparison_range. | |
| sort_direction | No | Ranking direction. Defaults to QWA's ranked-table rule: descending for clicks/impressions/CTR, ASCENDING for position (lower is better), so ranking by position returns the BEST-ranked rows exactly as the app does. Pass "desc" explicitly for the inverse question — the WORST-ranked rows. | |
| date_range_mode | No | REQUIRED when granularity is set. Use "calendar" for YTD or another explicit calendar period: keep the requested start and return only complete buckets inside it. Use "rolling" for "last N days/weeks/months/quarters": preserve N complete buckets by shifting the full window backward when needed. | |
| comparison_range | No | Snapshot PoP only: add deltas vs this explicit range, e.g. "2026-04-01 to 2026-04-30". If the request also asks for a day/week/month/quarter series, do NOT call gsc_breakdown; call gsc_dimensional_trend exactly once and pass the second range there. |