Top search queries
query_top_queriesUse this when the user asks which search queries bring a property the most clicks. Returns the top queries over a date range: a wrapper around query_search_analytics. Not for totals: use get_site_summary. Rows are sorted by clicks, highest first; ctr is a 0-100 percentage. Query rows cover only the queries Google lists: coverage.hiddenClicksShare (0-1) is the share of clicks with no query row, so quote totals from coverage.siteTotals, or coverage.filteredTotals when coverage.scope is "filtered", not summed rows. Served from the ClickHouse warehouse (longer history) when available, else the live Search Console API (dataSource says which). Date range is optional: omit startDate/endDate to analyze the last 28 settled days (data lags ~2-3 days).
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": {
"siteUrl": "<siteUrl>"
},
"name": "query_top_queries"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| brand | No | Optional. Narrow to queries matching the property's branded keywords ('branded') or to all others ('non_branded'). Needs branded keywords set (update_site brandedKeywords); see get_filter_options. | |
| limit | No | Rows to return per call (default 100, max 1000). | |
| offset | No | Rows to skip. Use pagination.nextOffset from a previous call to get the next page. | |
| endDate | No | Optional. Window end as YYYY-MM-DD (e.g. 2026-05-31). You do NOT need to know today's date or the latest available date: omit this and the server uses the latest settled Search Console date (data lags ~2-3 days behind today). Never pass null or the string "null". | |
| siteUrl | Yes | ||
| startDate | No | Optional. Window start as YYYY-MM-DD (e.g. 2026-05-03). You do NOT need to know today's date. Omit BOTH startDate and endDate to analyze the last 28 settled days automatically (Search Console data lags ~2-3 days). Never pass null or the string "null". | |
| searchType | No | Search type: web (default), image, video, news (the News tab), discover, googleNews (news.google.com), webMultimodal (Google Lens, Circle to Search and image uploads; data from 2026-02-20; not part of all), or all (web + image + video + news + discover combined, position impression-weighted, like the app's "All" filter). Discover, googleNews and webMultimodal carry no query dimension, so query-level results for them are empty; Discover and googleNews also carry no position: it reads null, not 0. | web |
| contentGroupId | No | Optional. Narrow to pages in this content group (id from get_filter_options or list_content_groups). Groups whose rules cannot be applied as a filter are refused; get_filter_options says which. | |
| topicClusterId | No | Optional. Narrow to queries in this topic cluster (id from get_filter_options or list_topic_clusters). Clusters whose keywords cannot be applied as a filter are refused. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| new | No | ||
| hint | No | ||
| kind | No | Widget variant: "kpis", "table", or "sections". | |
| kpis | No | KPI cards (kind="kpis"). | |
| lost | No | ||
| note | No | Caveat about the result, when the tool returned one. | |
| rows | No | Data rows (kind="table"), each with every field of the tool's own row; columns name the ones drawn. | |
| notes | No | Caveats about the result, when the tool returned several. | |
| range | No | The window the numbers cover. | |
| scope | No | The brand, content group or topic cluster filter these numbers are narrowed to; absent when the call was unscoped and the numbers cover the whole property. | |
| title | No | ||
| blocks | No | Stacked sub-blocks (kind="sections"). | |
| counts | No | get_ranking_changes: the full size of each bucket before `limit`. | |
| deltas | No | get_site_summary: current minus previous (ctrPoints in percentage points). | |
| reason | No | ||
| source | No | ||
| thenBy | No | Secondary sort field, when the tool states one. | |
| account | No | ||
| columns | No | Column defs (kind="table"). | |
| current | No | get_site_summary: the window's totals (ctr 0-100, impression-weighted avgPosition). | |
| summary | No | Metric totals keyed by GA4 metric name. | |
| warning | No | A caveat that changes how the numbers read. | |
| coverage | No | How much of the property total the returned rows cover, with the property totals inline. Quote totals from here; do not sum the rows. | |
| declined | No | ||
| improved | No | ||
| nextStep | No | ||
| ordering | No | Sort order per list, when the result holds several lists. | |
| previous | No | get_site_summary: the comparison window's totals. | |
| sortedBy | No | Row field the rows are sorted by. | |
| timeZone | No | GA4 property's IANA reporting time zone. | |
| dailyRows | No | get_site_summary: the window day by day, oldest first. | |
| dimension | No | ||
| emptyText | No | ||
| scanLimit | No | ||
| siteScope | No | Set when GA4 numbers were narrowed to this site's hostnames because the property is shared with other sites. | |
| sortOrder | No | "asc" or "desc". | |
| thenOrder | No | The tie-break's direction, present only when it differs from sortOrder. | |
| totalRows | No | ||
| assistants | No | get_ga4_llm_traffic: one row per AI assistant (the table rows). | |
| comparison | No | The comparison window (get_site_summary, get_ranking_changes). | |
| dataSource | No | Where the numbers were read from: the warehouse or the live API. | |
| hasRevenue | No | ||
| pagination | No | Where this page of rows sits in the whole result, and how to fetch the next one. | |
| timeseries | No | get_ga4_overview with includeTimeseries: daily points, oldest first. | |
| partialDays | No | Requested days after settledThrough; their numbers are still incomplete. | |
| prevSummary | No | The comparison period's totals; null when it has no GA4 data. | |
| currencyCode | No | ||
| dataMaturity | No | ||
| emptyBecause | No | ||
| ga4OnlyCount | No | ||
| gscOnlyCount | No | ||
| hasEcommerce | No | ||
| landingPages | No | get_ga4_llm_traffic: landing pages of AI assistant sessions. | |
| matchedCount | No | ||
| methodLimits | No | ||
| hasComparison | No | ||
| notConfigured | No | ||
| totalSessions | No | ||
| prevTimeseries | No | The comparison period's daily points; null when it has no GA4 data. | |
| reauthRequired | No | ||
| settledThrough | No | Last day the data is complete through. | |
| comparisonRange | No | The comparison window of a GA4 view tool; null when there is none. | |
| ecommerceSummary | No | ||
| sourceTimeseries | No | get_ga4_llm_traffic with includeDailySplit: daily sessions per assistant. | |
| comparisonHasData | No | false when the comparison period has no data at all, so there is no comparison. | |
| matchedClickShare | No | A 0-1 fraction of the named-query clicks the estimates cover. | |
| prevTotalSessions | No | ||
| previousDailyRows | No | get_site_summary: the comparison window day by day, oldest first; absent for a window over 180 days. | |
| llmShareOfSessions | No | A 0-1 fraction. | |
| coverageUnavailable | No | Why coverage is null, when it is. | |
| warehouseLatestDate | No | Newest day the warehouse holds for the property; days after it in the range are missing, not zero. | |
| prevEcommerceSummary | No | ||
| prevLlmShareOfSessions | No |