Paginate query results

  • The Merchant Center Query Language allows you to control the number of rows retrieved and navigate through large datasets using pageSize and pageToken.

  • pageSize determines the maximum rows per request, defaulting to 1000, while pageToken specifies the page to retrieve, starting with the first page if unspecified.

  • To get subsequent pages, use the nextPageToken received in the previous response, ensuring all other query parameters remain consistent.

  • The nextPageToken will not be included in the response for the final batch of rows.

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.