Query the Search Analytics API: filters and pagination
Read the conclusion first
Define what one result row means, then keep the property, dates, type, filters and aggregation stable across pagination. More pages do not guarantee complete data. A page-query mapping requires joint dimensions; separate top-page and top-query lists cannot be joined by row order.
Applicable conditions
Applies to automated search report development. The current AISEO Site page list only retrieves limited top rows.
Before you open the report
The exact property, dates, search type, dimensions, filters, dataState and pagination parameters.
Use one concrete URL or report first. Keep account credentials and private visitor data out of shared notes.
Steps and verification
Choose the row key for the actual question
For the task ‘which query brought clicks to this page’, request page and query together or filter the page while grouping by query. Record dimension order because response keys follow that order. Use the exact property string, including sc-domain:example.com for a Domain property.
Start with completed dates and dataState final. Search dates use Pacific Time; preserve that convention when joining other systems. Additional dimensions increase detail and can change available rows, so do not request every dimension without a specific use.
Keep a reproducible request
Teaching request: {"startDate":"2026-09-01","endDate":"2026-09-28","type":"web","dimensions":["page","query"],"aggregationType":"auto","rowLimit":1000,"startRow":0,"dataState":"final"}. This is an example, not a call against a customer's property.
Add deliberate filters for the task and retain the request with its response. A page dimension or page filter is incompatible with byProperty aggregation; use a supported option and check the returned aggregation. API CTR is a ratio: 0.02 corresponds to 2%, not 0.02%.
Page through one fixed result definition
Increase startRow by the requested row limit while preserving other parameters. Stop on an exhausted result and track row keys, errors and the collected range. The current rowLimit ceiling is 25,000; a larger desired inventory still needs supported pagination and bounded work.
Results are top rows subject to internal limitations. Tied click counts do not have a guaranteed stable order, and fresh data can move during collection. Preserve duplicate checks and explain the remaining limits rather than presenting pagination as proof of a complete query database.
Represent omissions and errors honestly
A successful empty page beyond the result set is not an authorization error. With date grouping, dates without data can be omitted. Compare broad totals and query detail only with their aggregation and privacy boundaries stated; do not synthesize unseen queries.
If recent data is required, mark it preliminary and inspect available incompleteness metadata. Close with the request definition, actual collected rows, data cutoff and limits. AISEO Site's current limited top-row views should retain those boundaries in both display and AI analysis.
Common mistake: Pagination to the end is called all data
Boundaries such as API-returned top rows still affect available data; source limitations must be stated clearly.
How to decide when you encounter different situations
Match your actual observation to a row before changing the page. If it does not match, collect the missing evidence first.
| What you see | Next step | How to confirm |
|---|---|---|
| Page table and query table are independent | Do not associate by row number | Use combined dimensions or native filters |
| No new rows after pagination | Determine pagination boundaries and limits | Do not call it absolutely complete |
| Fresh data is incomplete | Mark dataState and cutoff | Do not hard-compare with complete days |
Paging the top rows does not expose every query
Teaching scenario. Names, URLs and numbers illustrate the method; they are not customer or measured site results.
- What you observe
- Teaching example: page one contains 100 rows and page two 20. Another request returns page rows sorted independently from query rows.
- What it establishes
- An ending page indicates this request’s pagination boundary, not all possible queries. Independent page/query tables cannot be joined by row number.
- What to do next
- Use supported combined dimensions or exact filters for the question. Advance startRow by the returned page size, preserve request parameters and respect the documented reporting limits.
What counts as a checked result
Check for duplicate keys and unchanged parameters across pages. Label the dataset’s scope and completeness limits; do not describe it as every search query.
If a required check fails, keep the error and return to the matching decision branch. A blank record means unverified, not passed.
Leave with a checked result, not another vague instruction
- Your deliverable
- A reproducible request and collected row-key inventory with honest coverage limits.
- Stop and resolve this first
- Do not join separate lists by order or interpret pagination exhaustion as full query coverage.
Record missing evidence in the worksheet below. An unresolved test is useful information; a blank field is not a pass.
Checklist for this page
Fill in your own check results, then decide the next step. Blank means not yet verified, not normal. Content is saved only in the current local session and is not submitted to the server or AI.
Frequently asked questions
Are more dimensions always better?
Finer dimensions increase complexity and data limitations; query according to the actual analysis task.
Can I compare fresh and final data as if both were complete?
Keep dataState and the latest available date visible. Incomplete dates need separate treatment before interpreting a change.
Official materials and usage boundaries
This page provides operational judgment and checking methods, and does not show customer success cases. Calculation examples and request samples are teaching materials, not actual website metrics. Google's reports, conditions, and interfaces may change; please refer to the current official documentation.
Read the corresponding Google official documentationContinue with the relevant tool
Use the product's page and query views to review search opportunities. Keep your custom API filters and pagination evidence when comparing the same scope.
See how it works →