Skip to main content
The StoreRouter search endpoint returns results one page at a time. When more products match your query than fit on a single page, the response includes a nextCursor field you pass back to fetch the next page. This cursor-based model ensures you can iterate through a full result set consistently, even as the underlying catalog updates.

How cursor-based pagination works

Each POST /v1/products/search response contains:
  • items — the current page of products (up to limit items)
  • nextCursor — a string token encoding the engine’s continuation state, or null if you have reached the last page
To advance to the next page, send the same request again with the nextCursor value passed as cursor. Keep repeating until nextCursor is null.
Cursors are opaque. Do not parse, decode, or construct them manually. Their internal format may change between API versions. Pass back exactly the nextCursor the previous page returned, with the same request body. A cursor that is malformed, was issued under a different cursor version, or no longer maps onto the current query returns 400 with {"detail": "invalid cursor"}. Restart from page 1 by omitting cursor.
Page 1 is ranked by relevance. Later pages continue in quality-score order from page 1’s last result, so a product can repeat across pages. De-duplicate by uuid when you concatenate pages.

The pagination pattern

1

Send your initial search request

Issue POST /v1/products/search with your filters and an optional limit (1–100, default 50). Do not include a cursor on the first request.
2

Check nextCursor in the response

If nextCursor is null, the response is the only (or last) page — you are done. If nextCursor is a non-null string, there are more results.
3

Send the next request with cursor

Repeat the same request, passing the nextCursor value as cursor. Keep the rest of the request body — including catalogs, facets, and relax if you sent them — identical to the original request.
4

Repeat until nextCursor is null

Continue sending requests until nextCursor is null. That response contains the final page of results.

Complete pagination loop

The examples below collect all matching products into a list, de-duplicated by uuid. For large catalogs, consider processing each page as it arrives rather than accumulating everything in memory.

The limit parameter

Set limit to control how many items the API returns per page. The valid range is 1–100 and the default is 50. Smaller page sizes reduce response latency for interactive use cases. Larger page sizes reduce the total number of round trips for batch jobs. Keep limit consistent across pages: changing it mid-iteration does not cause an error, but it may produce unexpected page boundaries.
For batch export jobs that process the entire catalog, limit: 100 minimizes the number of API calls. For interactive search UIs where the user sees results one page at a time, limit: 20 or limit: 25 keeps each response fast.