V1 and V2 pagination

Search endpoints return results in pages. This page documents the pagination object you send in a search body, the pagination object you get back, and the limits on page size and sorting.

Key points on this page:

• You choose the page in the request body, with page, page_size, and order.
• A search with no pagination field returns the first 25 records.
• The response includes counts, including total_count, so you know how many pages remain.
• page_size can't exceed 100 on product search.
• Sorting a result set of more than 10000 products returns 428.

Request pagination

Add a pagination object to the search body. All three fields are optional:

This request returns page 3 of the results, with 25 records per page, sorted by SKU from Z to A:

{
  "filters": [],
  "attributes": ["sku", "label"],
  "pagination": {
    "order": "-sku",
    "page": 3,
    "page_size": 25
  }
}

Sort results

The order field is a string made of an optional minus sign followed by the label of the field to sort by. With no minus sign the order is ascending, and with a minus sign it's descending.

You can sort by a field that isn't in attributes, but the field isn't returned.

Read the pagination response

Search responses return a pagination object next to data. It describes the page you got and the full result set:

{
  "data": [],
  "pagination": {
    "count": 1,
    "order": null,
    "page": 1,
    "page_size": 25,
    "total_count": 3
  }
}

Use total_count and page_size to work out how many pages there are, and loop from page 1 until you reach the last one. Only search operations return a pagination object. A request for a single record doesn't.

Limits

The following limits apply to product search. V2 product search documents the same ones.

To avoid the 428, narrow the search with filters until it matches 10000 products or fewer, or leave order empty. See Filtering and search for how to narrow a search.