Page through results

Page Summary

Google Ads API v19 and later use a fixed page size of 10,000 rows, and the page_size field is removed and cannot be set.
GoogleAdsService.Search splits results into multiple responses, each containing 10,000 objects.
To retrieve subsequent pages of results, you need to send the request again, updating the page_token with the next_page_token from the previous response.
Client libraries automatically handle paging, while REST users must explicitly request each new page.
The Google Ads API caches the entire dataset internally, making subsequent requests faster, provided the query remains exactly the same.
For manual paging needs, retrieve and store results locally to build custom pagination logic.

You can page through results retrieved with GoogleAdsService.Search instead of downloading the entire result set at once. For an overview of reporting with the Google Ads API, see the Reporting overview.

Search returns fixed pages of up to 10,000 rows. Setting page_size in SearchGoogleAdsRequest is deprecated and returns a RequestError.PAGE_SIZE_NOT_SUPPORTED error.

Example query and pagination

Consider the following query:

SELECT
  ad_group.id,
  ad_group_criterion.type,
  ad_group_criterion.criterion_id,
  ad_group_criterion.keyword.text,
  ad_group_criterion.keyword.match_type
FROM ad_group_criterion
WHERE ad_group_criterion.type = KEYWORD

If your account contains 50,000 keywords, the result set contains 10,000 GoogleAdsRow objects in the first response, along with a next_page_token.

To retrieve the next 10,000 rows, send the request again, but update the request's page_token to the response's next_page_token:

{
  "query": "SELECT ad_group.id, ad_group_criterion.type, ad_group_criterion.criterion_id, ad_group_criterion.keyword.text, ad_group_criterion.keyword.match_type FROM ad_group_criterion WHERE ad_group_criterion.type = KEYWORD",
  "pageToken": "CN3q9...example_token..."
}

Note that next_page_token is not populated in the response that contains the last batch of rows.

Our client libraries handle paging automatically. You only have to iterate through the rows of the response. When all rows in the current page have been returned, the client library fetches a new page of rows automatically on your behalf until the entire dataset is retrieved. If using REST instead of gRPC, you must explicitly make a request for each new page.

Caching and page token expiration

The Google Ads API internally caches the dataset so that subsequent page requests are faster than the initial request. Note that next_page_token values have a limited time to live (TTL) and expire if not used within a short period (around two hours). If a page token expires, the API returns an error and you must start a new query.

Your query must remain identical in subsequent requests to take advantage of the cached data. Subsequent paged requests don't count as additional operations toward your daily operation quota for Explorer access and Basic access. If the query differs and is sent along with the same page token, an error is returned.

Streaming

Reports in the UI