Pagination

List endpoints rarely return everything at once. Pagination splits large result sets into manageable pages. Three patterns dominate.

Offset Pagination

?offset=0&limit=50, then ?offset=50&limit=50. Simple and lets you jump to a page, but slow for deep offsets because the database scans and discards rows. Items may shift if data changes mid-iteration.

Cursor Pagination

The API returns a cursor (an opaque token pointing to the last item). The next request passes ?cursor=<token>. Cursors are stable under concurrent writes and fast for large datasets. Stripe, Twilio, and Supabase use cursors. You cannot jump to page N - you must walk forward.

Page-Based Pagination

?page=2&per_page=50. Convenient for UI page numbers. Many APIs also return total and total_pages. Like offset pagination, it degrades on deep pages.

Best Practices

• Always follow Link or next URLs the API provides rather than hand-crafting offsets.
• Detect the end of results (empty page, no next cursor) and stop.
• Beware of infinite loops if data is mutating; cap iterations.
• For bulk export, prefer a dedicated export endpoint or webhooks.
• Store the last-seen cursor to resume after a crash.