Learning Tips | Published Nov 17, 2026 | 8 min read

API Pagination: Offset vs Cursor and Reliable Next Pages

Compare offset and cursor pagination, stable ordering, page-size limits, and continuation tokens with practical API and SQL examples.

Diagram compares offset pagination skipping rows with cursor pagination continuing through a next-page token after a stable sort key

Pagination keeps collection endpoints responsive as data grows, but the choice between offsets and continuation tokens affects ordering, performance, and what clients must preserve between requests. This guide compares the approaches and gives a practical checklist for designing and consuming paginated APIs.

Returning an entire collection in one response can create large payloads, slow queries, and brittle clients. Pagination sets a manageable upper bound on each response and gives a client a defined way to continue. The two common designs are numbered pages built with offsets and continuation cursors built around a position in the ordered result set.

Start with a stable order

Before choosing a paging mechanism, decide which records are in the collection and define an order that is deterministic. Sorting only by a timestamp is often insufficient because multiple records can share the same timestamp. Add a unique tie-breaker such as an ID so every item has one position.

For example, a PostgreSQL query might use ORDER BY created_at DESC, id DESC. The exact syntax depends on the database, but the principle applies to any API: every page must use the same filter and ordering rules. Without a unique order, an item can appear twice or disappear between pages even when the collection has not changed.

Offset pagination: simple pages and direct jumps

An offset request says how many ordered rows to skip and how many to return. In PostgreSQL, a request for the third group of 20 might look like:

SELECT id, title, created_at
FROM articles
ORDER BY created_at DESC, id DESC
LIMIT 20 OFFSET 40;

This maps naturally to page numbers and supports a “jump to page 8” interface. It is often a reasonable choice for small, relatively stable result sets, administrative tables, or interfaces where page-number navigation is important.

There are two trade-offs. First, a large offset may be costly because the database still has to compute rows that it skips. Second, inserts or deletes before the current offset can shift the boundaries: a client that requests page 1 and then page 2 may see a duplicate or miss a record if the collection changes between requests. A unique ORDER BY makes each individual query predictable, but it does not freeze the collection across multiple requests.

Cursor pagination: continue after a position

A cursor identifies where the previous response ended. With keyset pagination, the next query asks for rows after the last sort key rather than counting from the beginning. If the order is newest first by created_at and id, the next page can use a matching comparison:

SELECT id, title, created_at
FROM articles
WHERE (created_at, id) < (:last_created_at, :last_id)
ORDER BY created_at DESC, id DESC
LIMIT 20;

This tuple comparison is a PostgreSQL example; other databases may require an equivalent expression. The comparison direction must match the sort direction, and the cursor must carry every sort value needed to resume. A cursor can avoid the growing skip work associated with deep offsets and is often a better fit for feeds, event streams, or large collections.

Many public APIs expose an opaque page_token instead of raw sort values. The server returns a next_page_token, and the client sends it back on the next request. The token should represent continuation state, not grant access: authenticate and authorize every request as usual. Keep filters and sort options unchanged while following a token unless the API explicitly documents otherwise. Tokens may expire, so clients should be prepared to restart the listing when the server says one is invalid.

Design the response contract clearly

A predictable API contract answers four questions: what is the maximum page size, how does a client request the next page, how does the response signal completion, and which request parameters must remain the same? A common shape is ?page_size=20&page_token=... with a response containing items and next_page_token. If the token is absent or empty, the API can define that there is no next page.

Document whether the service may return fewer items than requested. It can do so because of server limits, filtering, or a time budget; therefore, do not infer that a short page is always the last page. Follow the continuation field. Also define a sensible default and maximum page size, reject invalid negative values, and cap oversized requests so a client cannot ask the server for an unbounded response.

A total count is optional. Computing an exact count can be expensive on a large or frequently changing collection, and a count may be stale by the time the client reaches the last page. Include one only when the product needs it, and document whether it is exact, estimated, or tied to a snapshot.

Consume pages without gaps or runaway loops

  1. Send the documented filters, sort order, and requested page size.
  2. Process each item in the response, then read the documented continuation token or link.
  3. Stop only when the API's end-of-collection signal says there is no next page.
  4. For long-running exports, persist the token and relevant query parameters, and handle token expiry or transient errors according to the API contract.
  5. Use a request limit, retry policy, and duplicate-safe processing when the job may be restarted.

Cursor pagination can reduce boundary shifts caused by new rows inserted before the cursor, but it does not automatically provide a consistent snapshot. Updates to sort keys, deletions, permissions, or records added later can still affect what a client observes. If an export must represent one precise point in time, the API needs an explicit snapshot or versioning mechanism.

Choose based on the user journey

NeedLikely fitWatch for
Jump to a numbered pageOffset and limitDeep offsets and shifting results
Walk a large or changing feed forwardCursor or keyset tokenStable sort keys and token handling
Export one consistent snapshotCursor plus snapshot/version supportA cursor alone is not a snapshot
Simple, small, mostly static listEither; choose the simplest contractAlways document bounds and ordering

There is no universal winner. Keep offset pagination where direct page jumps are useful and data volume is manageable. Prefer a cursor for deep sequential traversal, while designing stable ordering and a clear token contract. For more lessons on backend API design, explore the Jaipur Engineers course catalog.

Further reading

Want a structured Java learning path?

Explore Jaipur Engineers course options to connect Java fundamentals, debugging, backend development and project practice in a guided learning plan.

Explore the Java program   Ask for course guidance