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.
Pages are consecutive slices of one ranked list, so they don’t overlap. A search with q ranks a bounded set of products, so it ends after a limited number of pages. A product can still repeat if the catalog changes between requests, so 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.

Brand product browsing uses offsets

GET /brands/{brand}/products uses stable UUID order and a server-derived nullable nextOffset, rather than Product Search’s relevance cursor. Follow that value even when the projected products list is empty. total counts scoped source rows before public projection. At 24 source rows per page, page 500 starts at offset 11976. It is the last supported page. nextOffset is null when the source is exhausted or another page would exceed that bound. An offset above 11976 returns 422. This is bounded browsing, not an export of the full catalog.