Paginate query results

The Merchant Center Query Language provides the following fields for pagination:

  • pageSize: The maximum number of rows to retrieve in a single request. Defaults to the maximum page size of 1000 rows.
  • pageToken: The token of the page to return. If unspecified, the first page is returned.
  • nextPageToken: The pageToken value to get the next page from an accounts.reports.search call.

When a pageToken is provided, all other parameters in the call must match the previous call to avoid unexpected behavior.

For example, if you make the following query on an account that has 100,000 offer_id values, and the pageSize is set to 200, the result contains only 200 ReportRow objects in the first response, along with a nextPageToken:

SELECT offer_id, impressions, clicks, click_through_rate
FROM product_performance_view
WHERE date BETWEEN '2023-12-01' AND '2023-12-31'

Here's sample response (the first five results, and the nextPageToken):

{
  "results": [
    {
      "productPerformanceView": {
        "offerId": "12345",
        "clicks": "0",
        "impressions": "59",
        "clickThroughRate": 0
      }
    },
    {
      "productPerformanceView": {
        "offerId": "12346",
        "clicks": "9625",
        "impressions": "276695",
        "clickThroughRate": 0.034785594246372356
      }
    },
    {
      "productPerformanceView": {
        "offerId": "12347",
        "clicks": "148",
        "impressions": "22045",
        "clickThroughRate": 0.0067135404853708325
      }
    },
    {
      "productPerformanceView": {
        "offerId": "12348",
        "clicks": "11",
        "impressions": "1100",
        "clickThroughRate": 0.01
      }
    },
    {
      "productPerformanceView": {
        "offerId": "12349",
        "clicks": "569",
        "impressions": "62977",
        "clickThroughRate": 0.0090350445400701838
      }
    },
    ...
  ],
  "nextPageToken": "CMgB"
}

To retrieve the next 200 rows, send the request again with the same page size, but update the request's pageToken to the nextPageToken from the preceding response.