Stay organized with collectionsSave and categorize content based on your preferences.
In order to handle result sets containing a large number of rows, Merchant
Center Query Language supports pagination. Two parameters are available to
control pagination in thereports.searchrequest
body:page_sizeandpage_token, in addition to one output field in theresponse
body:next_page_token.
Thepage_sizeparameter specifies the maximum number of rows to retrieve in a
single request. If unspecified, it is automatically set to the maximum page size
of 1000 rows.
Thepage_tokenparameter specifies the token of the page to return. If
unspecified, the first page is returned. To retrieve a subsequent page, the
value received as thenext_page_tokenfrom the previousreports.searchcall
should be provided as apage_token. When apage_tokenis provided, all other
parameters in the call should match the previous call that returned thepage_tokento avoid unexpected behavior.
For this query, assume the account contains 100,000offer_idsand thepage_sizeis set to 200. The result set will then contain 200ReportRowobjects in the first response, along with anext_page_token.
To retrieve the next 200 rows, send the request again with the same page size,
but update the request'spage_tokento the previous response'snext_page_token.
Here is a response body example (the first five results plus thenext_page_token):
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Missing the information I need","missingTheInformationINeed","thumb-down"],["Too complicated / too many steps","tooComplicatedTooManySteps","thumb-down"],["Out of date","outOfDate","thumb-down"],["Samples / code issue","samplesCodeIssue","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-08-13 UTC."],[[["\u003cp\u003eThe Merchant API is the new version of the Content API for Shopping and represents the future of the platform.\u003c/p\u003e\n"],["\u003cp\u003eMerchant Center Query Language supports pagination to handle large result sets using \u003ccode\u003epage_size\u003c/code\u003e and \u003ccode\u003epage_token\u003c/code\u003e parameters.\u003c/p\u003e\n"],["\u003cp\u003eThe \u003ccode\u003epage_size\u003c/code\u003e parameter controls the maximum number of rows returned per request, defaulting to 1000.\u003c/p\u003e\n"],["\u003cp\u003eTo retrieve subsequent pages of data, use the \u003ccode\u003enext_page_token\u003c/code\u003e from the previous response as the \u003ccode\u003epage_token\u003c/code\u003e in the next request.\u003c/p\u003e\n"],["\u003cp\u003eThe \u003ccode\u003enext_page_token\u003c/code\u003e will not be included in the response containing the final batch of rows.\u003c/p\u003e\n"]]],["The Merchant API beta is introduced as the new version of the Content API for Shopping. Pagination in Merchant Center Query Language uses `page_size` (maximum 1000 rows) and `page_token` to handle large result sets. `page_size` defines the number of rows per request, and `page_token` specifies which page to return. Subsequent pages are fetched by using the previous response's `next_page_token`. The absence of `next_page_token` indicates the last page.\n"],null,["# Paginate query results\n\nIn order to handle result sets containing a large number of rows, Merchant\nCenter Query Language supports pagination. Two parameters are available to\ncontrol pagination in the [`reports.search` request\nbody](/shopping-content/reference/rest/v2.1/reports/search#request-body):\n`page_size` and `page_token`, in addition to one output field in the [response\nbody](/shopping-content/reference/rest/v2.1/reports/search#response-body):\n`next_page_token`.\n\nThe `page_size` parameter specifies the maximum number of rows to retrieve in a\nsingle request. If unspecified, it is automatically set to the maximum page size\nof 1000 rows.\n\nThe `page_token` parameter specifies the token of the page to return. If\nunspecified, the first page is returned. To retrieve a subsequent page, the\nvalue received as the `next_page_token` from the previous `reports.search` call\nshould be provided as a `page_token`. When a `page_token` is provided, all other\nparameters in the call should match the previous call that returned the\n`page_token` to avoid unexpected behavior.\n\nExample: \n\n SELECT\n segments.offer_id,\n metrics.impressions,\n metrics.clicks,\n metrics.ctr\n FROM MerchantPerformanceView\n WHERE segments.date BETWEEN '2021-12-01' AND '2021-12-31'\n\nFor this query, assume the account contains 100,000 `offer_ids` and the\n`page_size` is set to 200. The result set will then contain 200 `ReportRow`\nobjects in the first response, along with a `next_page_token`.\n\nTo retrieve the next 200 rows, send the request again with the same page size,\nbut update the request's `page_token` to the previous response's\n`next_page_token`.\n\nHere is a response body example (the first five results plus the\n`next_page_token`): \n\n {\n \"results\": [\n {\n \"segments\": {\n \"offerId\": \"12345\"\n },\n \"metrics\": {\n \"clicks\": \"0\",\n \"impressions\": \"59\",\n \"ctr\": 0\n }\n },\n {\n \"segments\": {\n \"offerId\": \"12346\"\n },\n \"metrics\": {\n \"clicks\": \"9625\",\n \"impressions\": \"276695\",\n \"ctr\": 0.034785594246372356\n }\n },\n {\n \"segments\": {\n \"offerId\": \"12347\"\n },\n \"metrics\": {\n \"clicks\": \"148\",\n \"impressions\": \"22045\",\n \"ctr\": 0.0067135404853708325\n }\n },\n {\n \"segments\": {\n \"offerId\": \"12348\"\n },\n \"metrics\": {\n \"clicks\": \"11\",\n \"impressions\": \"1100\",\n \"ctr\": 0.01\n }\n },\n {\n \"segments\": {\n \"offerId\": \"12349\"\n },\n \"metrics\": {\n \"clicks\": \"569\",\n \"impressions\": \"62977\",\n \"ctr\": 0.0090350445400701838\n }\n },\n ...\n ],\n \"nextPageToken\": \"CMgB\"\n }\n\n| **Key Point:** The `next_page_token` is not populated in the response that contains the last batch of rows."]]
