Sous Chef API
Sous Chef Management API
Documentation

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–100 (both ends inclusive) and defaults to 50 when omitted. Anything outside that range — 0, 2.5, or 101 — is a 400 naming the bound it crossed. In particular an over-large limit is not clamped down: a truncated page that looks like a whole one is a silent data loss for the caller, so asking for more than 100 is an error you read once rather than rows you never find out you missed.
  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. Today the position it holds is a row count, which is what the next section is honest about; 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: Your filters do not match the original filters. Please do not send filters on page 2 onward; we use the ones encoded in the cursor.
  • 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.

The cursor can not be edited: a cursor that was changed, cut short or made up is a 400. It also never changes whose data you read; that always follows the API key.

The position is counted in rows from the start of the result. So it does not protect you from writes made while you page: a row inserted or removed before your position moves every later row by one, and the next page can repeat a row you already have or skip one you have not seen.

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: a row created while you are paging lands wherever it belongs in the ordering, which may be a page you have already read.

Ordering is a different question, and it depends on the feed. Most collection reads have a fixed order — the 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, still do not lean 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, and it defaults to createdAtDesc — newest first, which is what you want for "what has arrived since I last polled".

sort: "createdAtAsc" with no cursor is the other question worth asking: your very first order. Send page: { "limit": 1 } with it, add storeId to ask it of one storefront, and 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 the cursor holds), 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 naming the number.

That is not a retention limit — every order we hold is still readable. It is a limit on one access pattern. Reaching row 10,001 by paging means re-counting ten thousand rows the database has already handed you, and it is the shape that gets expensive for us both. The cheaper way to ask the same question is a narrower [createdAtStartDate, createdAtEndDate) window, and windows have no width limit at all — so you lose nothing and your loader gets checkpoints for free.

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.