GSC_QUERY
Custom Google Search Console query with full control over dimensions and filters.
=GSC_QUERY(startDate, endDate, [dimensions], [limit], [filterDimension], [filterOperator], [filterValue], [siteUrl])Returns: 2D array with columns for each selected dimension + Clicks, Impressions, CTR, Position
Overview
GSC_QUERY is the most flexible and powerful Search Console function, giving you complete control over what data you retrieve and how it is structured. While the other GSC functions cover common use cases with simplified parameters, GSC_QUERY lets you specify custom dimensions, apply filters, and combine multiple data axes in a single request. It mirrors the full capabilities of the Google Search Console API's searchAnalytics.query endpoint, making it possible to build virtually any search performance report.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
startDate | string | Yes | Start date in "YYYY-MM-DD" format or relative format like "-30d" for 30 days ago. |
endDate | string | Yes | End date in "YYYY-MM-DD" format or relative format like "-1d" for yesterday. |
dimensions | string | No (query) | Comma-separated list of dimensions: query, page, country, device, date. Defaults to "query". |
limit | number | No (100) | Maximum number of rows to return. Defaults to 100, max 25000. |
filterDimension | string | No | The dimension to filter on: query, page, country, or device. |
filterOperator | string | No | The filter operator: "equals", "contains", or "notContains". |
filterValue | string | No | The value to filter by (e.g., a URL pattern, country code, or keyword). |
siteUrl | string | No | The site URL property from Search Console. If omitted, uses the default connected property. |
Examples
Queries by country
Get top queries broken down by country to understand geographic search performance.
=GSC_QUERY("-30d", "-1d", "query,country", 500)Output
| Query | Country | Clicks | Impressions | CTR | Position |
| best crm software | USA | 520 | 9400 | 5.5% | 3.1 |
| best crm software | GBR | 180 | 3200 | 5.6% | 3.4 |
| crm comparison | USA | 340 | 6100 | 5.6% | 4.2 |
| crm comparison | DEU | 95 | 2100 | 4.5% | 5.8 |
Daily click trends
Get daily total clicks and impressions for the last 14 days to chart overall search trends.
=GSC_QUERY("-14d", "-1d", "date", 14)Output
| Date | Clicks | Impressions | CTR | Position |
| 2025-03-01 | 1250 | 18500 | 6.8% | 12.3 |
| 2025-03-02 | 1180 | 17800 | 6.6% | 12.5 |
| 2025-03-03 | 1420 | 21200 | 6.7% | 11.8 |
Blog-only queries filtered by page
Get queries that only drove traffic to blog pages by filtering on the page URL containing "/blog/".
=GSC_QUERY("-30d", "-1d", "query", 200, "page", "contains", "/blog/")Output
| Query | Clicks | Impressions | CTR | Position |
| how to write a business plan | 890 | 14200 | 6.3% | 3.8 |
| business plan template | 720 | 12500 | 5.8% | 4.1 |
| startup business plan example | 540 | 8900 | 6.1% | 4.5 |
Non-branded traffic analysis
Exclude brand name queries to analyze only non-branded organic search performance.
=GSC_QUERY("-30d", "-1d", "query", 1000, "query", "notContains", "mycompany")Output
| Query | Clicks | Impressions | CTR | Position |
| project management tools | 980 | 22100 | 4.4% | 5.1 |
| task tracking software | 650 | 14800 | 4.4% | 6.3 |
| team collaboration app | 520 | 11200 | 4.6% | 5.8 |
Mobile vs Desktop performance by page
Break down page performance by device type to identify pages that underperform on mobile.
=GSC_QUERY("-30d", "-1d", "page,device", 500)Output
| Page | Device | Clicks | Impressions | CTR | Position |
| https://example.com/pricing | DESKTOP | 1800 | 24000 | 7.5% | 2.3 |
| https://example.com/pricing | MOBILE | 1200 | 19000 | 6.3% | 2.8 |
| https://example.com/blog/guide | DESKTOP | 950 | 13500 | 7.0% | 3.5 |
| https://example.com/blog/guide | MOBILE | 1100 | 16200 | 6.8% | 3.2 |
Use Cases
Geographic Performance Analysis
International companies analyze search performance by country to identify which markets have the strongest organic visibility and where to invest in localized content and SEO efforts.
Daily SEO Monitoring Dashboard
Agencies build daily monitoring dashboards using the "date" dimension to track click trends, spot sudden traffic drops, and correlate changes with Google algorithm updates or competitor activity.
Mobile-First SEO Optimization
Development teams compare mobile vs. desktop performance for key pages, identifying mobile-specific ranking issues that indicate Core Web Vitals problems or mobile usability issues.
Non-Branded Traffic Reporting
Marketing teams isolate non-branded search traffic using query filters to measure true organic search growth independent of brand awareness campaigns and direct brand searches.
Content Section Performance
Publishers filter by page URL patterns to compare performance across content sections (news, opinions, reviews, tutorials), guiding editorial resource allocation.
Algorithm Update Impact Assessment
SEO consultants use date-dimension queries around known algorithm update dates to measure impact on client sites, providing data-driven recommendations for recovery strategies.
Pro Tips
Use the "date" dimension without any other dimensions to get daily site-wide click totals, perfect for creating a simple traffic trend chart.
Filter by page "contains" a URL segment to analyze performance for specific site sections without needing to know every individual page URL.
Combine "query,date" dimensions with a query filter to track daily position changes for a specific keyword over time, creating a position trend line.
Use "query" dimension with a page filter (filterDimension "page", filterOperator "contains", filterValue "/product/") to find all keywords driving traffic to product pages specifically.
For non-branded traffic analysis, use filterDimension "query" with filterOperator "notContains" and your brand name as filterValue. This is more efficient than filtering after the fact.
The dimensions parameter controls what data columns are returned. You can request any combination of "query", "page", "country", "device", and "date" as a comma-separated string. For example, dimensions "query,country" returns search performance broken down by both keyword and country, while "page,device" shows page performance split by desktop, mobile, and tablet. The "date" dimension is especially powerful as it enables time-series analysis, letting you chart daily trends for clicks, impressions, and positions.
The filtering system allows you to narrow results to specific subsets of your data. Choose a filter dimension (query, page, country, or device), an operator (equals, contains, or notContains), and a value to include or exclude specific data. For example, filter by page "contains" "/blog/" to see only blog content performance, or filter by query "notContains" "brand name" to isolate non-branded search traffic. This eliminates the need for post-processing with FILTER functions and reduces data transfer.
GSC_QUERY is the function to use when the simpler GSC functions do not provide the exact data view you need. Whether you want country-level breakdowns, device-specific performance, daily trend data, or filtered subsets of your search analytics, this function delivers it with a single formula.
Common Errors
INVALID_DIMENSION: Unknown dimension specifiedCause: The dimensions parameter contains an unrecognized dimension name. Valid dimensions are: query, page, country, device, date.
Fix: Check for typos in the dimensions parameter. Use only the supported values: "query", "page", "country", "device", "date". Separate multiple dimensions with commas and no spaces (e.g., "query,country" not "query, country").
INVALID_FILTER: Filter operator must be equals, contains, or notContainsCause: The filterOperator parameter contains an unsupported operator value.
Fix: Use one of the three supported operators: "equals" for exact match, "contains" for partial match, or "notContains" for exclusion. These operators are case-sensitive in the parameter but apply case-insensitive matching to the data.
INCOMPLETE_FILTER: All three filter parameters must be provided togetherCause: Only some of the filter parameters (filterDimension, filterOperator, filterValue) were provided. All three are required when using filters.
Fix: When applying a filter, you must provide all three parameters: filterDimension (what to filter), filterOperator (how to filter), and filterValue (what value to match). If you do not want to filter, omit all three parameters.
Frequently Asked Questions
You can combine any of these dimensions: "query", "page", "country", "device", and "date". Pass them as a comma-separated string like "query,country" or "page,device,date". Each combination gives you a different data cross-section. Note that more dimensions result in more granular data and more rows, so you may need to increase the limit parameter.
Country values are returned as 3-letter ISO 3166-1 alpha-3 codes (e.g., "USA", "GBR", "DEU", "FRA", "JPN"). When filtering by country, use these same codes. For example, filterDimension "country", filterOperator "equals", filterValue "USA" to get only US search data.
The device dimension returns three values: "DESKTOP", "MOBILE", and "TABLET". When filtering by device, use these exact strings. For example, filterDimension "device", filterOperator "equals", filterValue "MOBILE" to get only mobile search data.
The current function supports a single filter per call. For multiple filter conditions, you can either make separate GSC_QUERY calls with different filters or apply a single API filter and then use Google Sheets FILTER function on the results for additional filtering. For most use cases, one filter combined with spreadsheet formulas is sufficient.
The "equals" operator matches the exact value (e.g., query equals "seo tools" matches only that exact query). The "contains" operator matches if the dimension value includes the filter string anywhere (e.g., page contains "/blog/" matches any URL with /blog/ in it). The "notContains" operator excludes matching values (e.g., query notContains "brand name" excludes all brand queries). These operators are case-insensitive.
When "date" is included as a dimension, results are broken down by individual day. Each row includes a date column in "YYYY-MM-DD" format along with the metrics for that specific day. This is essential for time-series analysis and charting trends. Without the date dimension, metrics are aggregated across the entire date range.
The maximum is 25,000 rows regardless of dimensions. However, combining multiple dimensions dramatically increases the number of unique rows. For example, 1,000 queries across 5 countries would produce up to 5,000 rows. If your data exceeds the limit, narrow your date range, add a filter, or reduce dimensions.
Yes, GSC_QUERY is the underlying power function. GSC_TOP_QUERIES is equivalent to GSC_QUERY with dimensions "query", GSC_TOP_PAGES with dimensions "page", GSC_PAGE_QUERIES with dimensions "query" and a page filter, and GSC_KEYWORD_POSITION with dimensions "query" and a query filter. The specialized functions are simpler to use for common cases.
Related Functions
GSC_TOP_QUERIES
Get top search queries from Google Search Console sorted by clicks.
GSC_TOP_PAGES
Get top pages from Google Search Console sorted by clicks.
GSC_PAGE_QUERIES
Get search queries driving traffic to a specific page.
GSC_KEYWORD_POSITION
Get average position for a specific keyword from Google Search Console.
Start using GSC_QUERY today
Install Unlimited Sheets to get GSC_QUERY and 41 other powerful functions in Google Sheets.
