API Pagination: Build Stable Lists That Scale for Founders

TL;DR — API pagination turns one large, changing list into predictable slices. Start with a stable sort order and cursor pagination for a list that will grow. Offset pagination is acceptable for small, mostly static back-office lists, but it can skip or repeat records when data changes between requests.

API pagination is a product contract, not a database trick. It tells a customer, integration, or mobile app how to move through a collection without downloading everything at once. The choice looks minor when an endpoint has 40 records. It becomes hard to reverse when that same endpoint feeds exports, dashboards, and automated jobs.

The useful founder question is not “which pagination syntax is popular?” It is: what must remain true while a client is halfway through this list? That answer determines the sort key, the token you issue, and whether a user can safely resume after a network failure.

Choose the model from the user journey

Offset pagination accepts a page number or an offset and a limit: ?offset=40&limit=20. It is easy to explain and enables a familiar “jump to page 12” interface. Its weakness is movement. If a new record is inserted ahead of the current offset, the next request can repeat an item. If a record disappears, it can skip one. That may be harmless for a staff directory; it is harmful for a billing export.

Cursor pagination returns a token derived from the last item the client received. The next request asks for items after that point. A cursor works best with an explicit, deterministic ordering such as created_at DESC, id DESC. The second field breaks ties. Without it, two records created in the same timestamp can move unpredictably.

Keyset pagination is the database-side version of that idea: query for rows after the last observed key rather than asking the database to count and discard earlier rows. It usually scales more gracefully for deep lists, but the API should hide the database detail behind an opaque cursor.

GitHub’s REST pagination guide is a useful public example of page traversal, while RFC 8288 defines the HTTP Link header model used for relations such as next. A response does not need to copy either design exactly. It does need one documented route forward.

Design the response before the query

A reliable cursor response contains three things: data, a next_cursor that is null when the collection ends, and metadata that explains the requested limit. Avoid exposing a raw primary key as the token. An opaque, signed or encoded cursor gives you room to change an index without breaking clients and makes misuse easier to reject.

Keep page size bounded. A limit of 10 is not morally better than 100; the right ceiling follows the payload size and client need. What matters is that the server chooses a default, caps a client’s requested value, and records the decision in the API documentation. This also works with API rate limiting: a caller that retries small pages can be helped, while an unbounded export can be offered as a separate asynchronous job.

A hypothetical decision

Imagine a support product listing tickets newest first. At 09:00 a manager opens page one, receiving 25 tickets and a cursor ending at ticket 500. At 09:01, three new tickets arrive. With a cursor defined by (created_at, id), page two continues after ticket 500; the manager does not reread tickets from page one. With offset=25, those new arrivals can push three old tickets into the range and create duplicates.

That does not mean cursor pagination is mandatory everywhere. A search result whose ranking changes for every request should state that it is a fresh search, and a spreadsheet-style admin grid may reasonably use offsets. The failure is promising stable traversal while using an unstable sort.

Failure modes to prevent

The common failures are easy to name:

• Sorting only by a mutable field, so an edit moves a record between pages.
• Returning a total count as if it were exact when calculating it is expensive or data is changing.
• Treating a cursor as trusted input rather than validating its shape, scope, and expiry.
• Reusing one cursor across filters. A cursor issued for “open tickets” must not work for “all tickets.”

The same care belongs in the storage layer. Database indexes should support the filter and sort used by the page; otherwise a fast-looking first page becomes an expensive deep traversal. If results are cached, the invalidation rule must match the list and its filters; see cache invalidation.

Acceptance checklist

• The endpoint has one documented default ordering and a tie-breaker.
• The response tells a client exactly how to fetch the next slice and how to detect the end.
• Limits have a default and a server-enforced maximum.
• Cursors bind to the query scope and fail clearly when malformed or expired.
• A test inserts and deletes records between requests and checks the promised behavior.

The founder decision is simple: optimize for a dependable export or workflow first, then add page-number convenience only where a person truly needs it. Pagination becomes infrastructure the moment another company automates against it.