search_performance
Your actual Google Search Console metrics for one period — clicks, impressions, CTR, average position, plus whole-site Unique Keywords / Unique Pages counts — at site, keyword or page grain, with top-N ranking. Use for "what were my total clicks last month?", "top 10 keywords by impressions", "how many unique keywords / pages do we rank for?", "non-brand organic clicks". Returns organic acquisition metrics (NOT paid) and does not guarantee organic conversion counts. For a complete paid-versus-organic comparison including conversions on both sides use paid_organic_performance_comparison. Set comparison_range for period-over-period changes; for biggest gainers/losers use seo_ranking_movement_report. When the user names two periods, date_range is the first period they named (the selected period) and comparison_range is the second, even when the first period is the earlier month — do not swap them. Deltas are the change from the earlier period to the later one, whichever was named first. A positive delta means the later period is higher. For average position, a positive delta is a worse rank.
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>"
},
"name": "search_performance"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| brand | No | Restrict to branded ("Yes") or non-branded ("No") demand. At grain:"site" (with no other granular filter) this returns a SINGLE site-level total as a keyword-attributed rollup with a coverage caveat; combined with granular filters or keyword/page grain it behaves as a per-row slice. | |
| grain | No | site = whole-site totals (one row); keyword/page = per-keyword/per-page rows (top-N). | site |
| top_n | No | Row cap at keyword/page grain (ignored at site grain). | |
| intent | No | Restrict to one intent (a customer keyword group). At grain:"site" (with no other granular filter) this returns a SINGLE site-level total as a keyword-attributed rollup with a coverage caveat; combined with granular filters or keyword/page grain it behaves as a per-row slice. Resolve the id with resolve_entity first. | |
| medium | No | Source medium. DEFAULTS to "google/organic" — these are organic Search Console metrics. Pass "google/cpc" for paid, or another medium to change it. (The underlying dataset blends organic + paid, so a default keeps "clicks" organic.) | |
| 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 — e.g. category, country, device, rank_bucket, traffic_source, search_type, page, query. e.g. category eq "Hosting": [{field:"category",op:"eq",value:"Hosting"}]; country in usa,can: [{field:"country",op:"eq",value:["usa","can"]}]; page contains "/blog/": [{field:"page",op:"contains",value:"/blog/"}]. regex/not_regex only on query/page. | |
| metrics | No | Which metrics to return; defaults to all four standard metrics. unique_keywords / unique_pages are whole-site COUNT totals (use at grain:"site"). | |
| sort_by | No | Sort metric at keyword/page grain. | impressions |
| 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 | Return a whole-site TIME SERIES bucketed by day / week / month / quarter instead of a single-period total — e.g. "weekly clicks over the last 26 weeks". Mutually exclusive with comparison_range (use one or the other). Trend is whole-site (grain / brand / intent / filters are ignored in v1). | |
| sort_direction | No | Ranking direction. Defaults to QWA's ranked-table rule: descending for clicks/impressions/CTR, ASCENDING for position (lower is better), so "top pages by position" returns the BEST-ranked rows exactly as the app does. Pass "desc" explicitly for the inverse question — the WORST-ranked pages. | |
| 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 | The second period the user named. date_range stays the first period (selected), even when it is earlier. "June vs July" → date_range is June and comparison_range is July, e.g. "2026-07-01 to 2026-07-31". Do not reorder so the later month becomes selected. Deltas still read from the earlier period to the later one. |