Validating Search Console Bulk Export Partitions and Retries
When Search Console sends performance data to BigQuery, it writes each day's data into date-based partitions, which keep each date's rows together.…
When you request image or video performance data from Google Search Console, the request’s type field selects the search category. In image and video data, query is the text people searched for. It does not identify an image they submitted through Google Lens or another visual search feature.
That distinction determines which filters make sense. Use type: "image" or type: "video" to analyze text queries associated with those search types. Use type: "webMultimodal" for traffic from Lens, Circle to Search, and image uploads; Google documents that the query dimension is unavailable for this traffic. The Search Analytics API reference lists these request types and their supported dimensions.
Each type value selects a separate set of search data. For image results, send a request with "type": "image"; for video search results, send another request with "type": "video". Use the same date range and dimensions when you want to compare them. The API also accepts "web" for the combined “All” tab and "webMultimodal" for multimodal searches. Because web represents the combined tab, do not assume it means text-only traffic.
The current request field is type; the older searchType field is deprecated. An image or video request does not show what image or other visual input someone used for a multimodal search. For that traffic, request supported dimensions such as page, country, or device without a query dimension.
A filter restricts which data the API returns. A dimension is a field that groups the remaining data into rows. You can filter by a dimension without including it in the output dimensions.
For example, this request keeps image-search rows whose text query contains “red shoes” and groups the results by page:
{
"startDate": "2026-10-01",
"endDate": "2026-10-31",
"type": "image",
"dimensions": ["page"],
"dimensionFilterGroups": [
{
"groupType": "and",
"filters": [
{
"dimension": "query",
"operator": "contains",
"expression": "red shoes"
}
]
}
]
}
The query filter narrows the returned rows, and page supplies each row’s page value. The contains operator ignores case. If you change the dimensions to ["query", "page"], the API groups results by both the text query and the page. If you change type to "video", the request returns video-search data instead of image-search data.
The API lets you filter with operators such as equals, contains, notEquals, notContains and regular-expression matching. equals is case-sensitive for query and page values. Filters in a group with "groupType": "and" must all match. For page-level analysis, use automatic aggregation rather than forcing property aggregation; Google’s performance-data guidance explains how grouping choices affect returned data.
A multimodal request should leave out query:
{
"startDate": "2026-10-01",
"endDate": "2026-10-31",
"type": "webMultimodal",
"dimensions": ["page", "device"]
}
This groups multimodal traffic by page and device. Adding query will not expose the image or other visual input as a text search term. If a request using an unsupported dimension returns an error or no data, check the current API reference for the dimensions supported by that search type.
Each returned row includes keys, clicks, and impressions. It also includes ctr and position. The keys array contains the values for the requested dimensions, in the same order as those dimensions. With ["query", "page"], keys[0] is the query and keys[1] is the page. Parse the array using the dimensions sent with that request, rather than assuming the same key order across different requests.
The ctr value is a decimal from 0 to 1, and position is the average position for that row. The response also includes responseAggregationType, which describes how the API aggregated the results. When you store rows, keep the request’s type, date range, dimensions in order, filters, and aggregation details with them. Your code can then interpret each row correctly, even after combining results from multiple requests.
A query-filtered total can be lower than an unfiltered image or video total. Search Console omits anonymized queries when a query filter is applied, and detailed query or page groupings can return less data than broader totals. Query rows are therefore not a reliable way to reconstruct every click or impression in a search type. The Search Console report overview also describes how anonymized queries and reporting limits affect visible query data.
When the output seems unexpectedly small, first confirm that the request uses the intended type. If you are investigating Lens, Circle to Search, or image-upload traffic, compare a webMultimodal request grouped by supported dimensions rather than expecting query rows. Then remove query filters and query grouping to see whether a broader report returns more data.
Check the date range next. The API treats both date endpoints as inclusive and uses Pacific Time. Google’s collection guidance says data is typically available after two to three days, but that timing is guidance rather than a guarantee. By default, the API returns finalized data. If you request dataState as all or hourly_all, recent data can be incomplete; inspect the response metadata for the first incomplete date or hour where the API provides it.
Also check pagination. rowLimit defaults to 1,000 and accepts values up to 25,000; startRow is a zero-based offset. The API guidance describes a separate limit of 50,000 rows per day per search type, sorted by clicks. Pagination retrieves additional available rows, but it cannot restore data omitted by Search Console’s limits or anonymization. For a closer look at differences between reporting surfaces, see reconciling Search Console API limits.
Page-level rows credit data to individual pages and can be grouped differently from property-level totals. Inspect responseAggregationType and avoid treating totals from differently grouped requests as directly interchangeable.
Give Vroni a GitHub issue, bug report, spec, or rough idea. It reads the repo, plans the change, writes code, runs checks, and works toward a review-ready pull request.
Take a look at vroni.com