search_console_analytics_query
Retrieve organic Google Search performance data from Search Console, including clicks, impressions, CTR, and average position. Group results by dimensions like query, page, device, or date.
Instructions
Query the Search Console Search Analytics API for organic Google Search performance data. Returns the raw 'rows' array from the searchAnalytics.query response: [{keys: [], clicks (int), impressions (int), ctr (float 0.0-1.0), position (float, 1-indexed average ranking)}]. Empty array when no data. Read-only. Use dimensions=['query'] for keywords, ['page'] for URLs, ['device'] for device split, ['date'] for a daily trend. For convenience shortcuts use search_console_analytics_top_queries / top_pages / device_breakdown; for before/after comparisons use search_console_analytics_compare_periods.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| site_url | Yes | Property identifier as registered in Search Console. For URL-prefix properties use the full URL including trailing slash (e.g. 'https://example.com/'). For Domain properties use the 'sc-domain:' prefix (e.g. 'sc-domain:example.com'). The property must be verified and accessible to the authenticated Google account. | |
| start_date | Yes | Inclusive start date in 'YYYY-MM-DD' format (e.g. '2026-03-01'). Search Console data typically lags 2-3 days, so 'today' returns no rows. Maximum lookback is 16 months. | |
| end_date | Yes | Inclusive end date in 'YYYY-MM-DD' format (e.g. '2026-03-31'). Must be >= start_date. Search Console data lags 2-3 days; requesting the last two days typically returns no rows. | |
| dimensions | No | Dimensions to group rows by. Allowed: query, page, country, device, date, searchAppearance. Omit for an ungrouped total (clicks/impressions/ctr/position across the window). Each additional dimension multiplies row cardinality — agents should usually pick 1-2. | |
| row_limit | No | Maximum rows to return. Default 100. Search Console API caps at 25000 per request; agents that need more should split the call by date range. | |
| dimension_filter_groups | No | Optional Search Console dimensionFilterGroups payload (list of {groupType: 'and', filters: [{dimension, operator ('equals'|'contains'|'notContains'|'notEquals'|'includingRegex'|'excludingRegex'), expression}]}). Passed through verbatim to the REST API. |