API docs
Sous Chef Management API
Request access

Pagination

Paging is cursor-based, and the cursor is asymmetric: it goes inside page on the way in and comes back at the top level on the way out.

The loop

  1. Send page: { "limit": 50 }. limit is 1 to 100 (both ends inclusive) and defaults to 50 when omitted. Anything outside that range (0, 2.5 or 101) is a 400. An over-large limit is not clamped down, because a truncated page that looks complete would hide rows from you.
  2. Read nextCursor from the top level of the reply.
  3. Send it back as page: { "cursor": "<nextCursor>" }. Send the cursor and nothing else. The cursor remembers the filters and sort of the first page, so every later page is the same query. From page 2 on, do not send filters. Repeating the same filters and sort alongside the cursor is tolerated; a filter with a different value is a 400. Only page.limit may change between pages.
  4. Repeat until nextCursor is absent. Absent means you have the last page.

For example, a fetchOrders sweep from a bookmark. The first page:

{
  "sort": "createdAtAsc",
  "createdAtStartDate": "2026-10-11T13:53:17.332Z",
  "page": { "limit": 50 }
}

Every later page needs only the cursor:

{ "page": { "cursor": "<nextCursor>" } }

and is the same read: createdAtAsc, from createdAtStartDate. Sending the first page's createdAtStartDate and sort again with it gives the same result.

Why a cursor and not an offset

The cursor is opaque so that we can change how it finds your place without changing your code. The contract is the cursor and nextCursor, not the way a position is encoded.

What the cursor holds

The cursor holds your position in the result and the filters and sort of the first page. That is what lets a page that sends only the cursor ask the same question as page one.

  • A page with a cursor and no filters runs under the first page's filters.
  • A page with a cursor and the same filters (and the same sort; leaving sort out and sending its default are the same) works as well. Order of fields does not matter. The order of ids inside a list does.
  • A page with a cursor and only some of the first page's filters (for example just sort) is fine too: the ones you leave out come from the cursor.
  • A filter you send with a different value is a 400. From page 2 on, do not send filters: the ones in the cursor are used.
  • page.limit may change on any page.

Filters travel inside the cursor, so a very long list (orderIds with several hundred ids) is held only up to a size limit. A cursor from a request past that limit cannot hand the list back: send the cursor with the complete, identical filters on every page, and a page that sends the cursor alone, or a different list, is a 400.

Do not edit a cursor or build one yourself: a cursor that was changed or cut short is a 400. A cursor never changes whose data you read; that always follows the API key.

What a cursor does not promise

  • It is opaque. Do not parse it, derive one, or store one as a durable bookmark across days.
  • Iteration is not snapshot-stable: when rows are created or removed while you page, a later page can repeat a row you already have or skip one you have not seen.

Ordering depends on the feed. Most collection reads have a fixed order, and the operation's reference page says which, for example "sorted by name ascending". fetchOrders lets you choose (see below). Either way the order is total: ties never reorder, so while nothing is written, two calls for the same page name the same rows.

For an exact backfill, do not rely on the cursor alone. Iterate contiguous [createdAtStartDate, createdAtEndDate) windows whose upper bound is in the past (such a window cannot gain rows while you page it) and reconcile on the row's own id. That is idempotent under any interleaving of concurrent writes, which paging alone is not.

Sorting the order feed

fetchOrders takes a sort on the order's creation time. It defaults to createdAtDesc (newest first), which suits "what has arrived since I last polled".

sort: "createdAtAsc" with no cursor answers a different question: your very first order. Send page: { "limit": 1 } with it, and add storeId to ask it of one storefront. The answer is one row rather than a sweep.

Ties on createdAt break on the order's id, so the ordering is total: while nothing is written, consecutive pages neither repeat nor skip a row. Orders created during a sweep can shift it by a row (see What a cursor does not promise), which is why an exact backfill pages a window that is already closed.

How deep a cursor goes

On most feeds you page to the end. On fetchOrders the cursor stops at 10,000 orders; past that you get a 400.

That is not a retention limit: every order we hold is still readable. It is a limit on paging depth. To read past it, use a narrower [createdAtStartDate, createdAtEndDate) window. Windows have no width limit, and each window gives your loader a checkpoint.

Time windows page too

fetchOrders bounds an order's creation time with createdAtStartDate (inclusive) and createdAtEndDate (exclusive). There is no maximum window width and no rolling retention ceiling, so a warehouse backfill can be one wide window with the cursor loop above nested inside it, or a loop over narrower windows if your loader prefers to checkpoint. Both bounds are optional; omit both for all-time.

Creation time is what makes a window loop exact: an order is created once, so it falls in exactly one window, and contiguous windows partition your history with no overlap and no gap. Do not size the windows against when an order was picked up. That is a different timestamp, typically minutes to hours later, and this filter does not read it.