تقسيم النتائج

Pagination

Every list answers in the same envelope, so you write one loop and not three:

{ "data": [ … ], "nextCursor": "…" | null }

Pass ?limit= to choose a page size. The default is 50 and the maximum is 200. To get the next page, send the previous response’s nextCursor back as ?cursor=. Keep going until nextCursor is null.

Cursors are opaque. Do not construct one, decode one, truncate one or URL-mangle one: pass back exactly the string you were given. A cursor that does not decode is refused with v1_invalid_cursor, which has its own code precisely because it means something different from a bad query parameter: it means the value we handed you was altered on the way back.

Paging is keyset-based, so a page is stable even while rows are being written behind you; it does not skip or repeat rows the way an OFFSET would.