REST API Pagination Patterns: Offset, Cursor, and Keyset Designs with Client Implementation Checklists
rest-apipaginationdatabasesbackendapi-design

REST API Pagination Patterns: Offset, Cursor, and Keyset Designs with Client Implementation Checklists

CCodeGuru Editorial Team
2026-11-16
7 min read

Compare offset, cursor, and keyset pagination, with REST response examples and checklists for reliable API clients and changing datasets.

Choosing the right REST API pagination pattern affects database load, result consistency, client complexity, and how reliably users can move through changing datasets. This guide compares offset, cursor, and keyset pagination, then provides implementation checklists for API designers and clients.

Overview

Pagination limits the amount of data returned in one response. Instead of sending every record, an API returns a bounded page and provides enough information for the client to request another one. A useful pagination design must define the page size, ordering, continuation method, response metadata, and behavior when records are added, changed, or deleted between requests.

The three common designs are:

  • Offset pagination: the client requests a number of records to skip and a page size, such as ?offset=40&limit=20.
  • Cursor pagination: the server returns an opaque continuation token that the client sends back to request the next page.
  • Keyset pagination: the client requests records after a known value, usually an indexed, unique sort key such as an ID or timestamp.
PatternBest fitMain advantageMain trade-off
OffsetSmall, relatively stable datasets and page-number interfacesSimple to understand and debugDeep pages can become slower and shift when rows change
CursorFeeds, timelines, and APIs with changing dataStable continuation without exposing sort detailsTokens need validation, expiry rules, and clear client handling
KeysetLarge tables with a suitable indexed orderingEfficient traversal of deep result setsRequires careful ordering and is less suited to arbitrary page jumps

There is no universally best pagination strategy. Start with the user experience and query shape. If clients must jump directly to page 25, offset may be appropriate. If clients mainly need “load more” behavior while new rows arrive, cursor or keyset pagination is usually easier to make consistent.

Checklist by scenario

Choose offset pagination for simple page navigation

Offset pagination is often the most accessible design for administrative screens, search results, and modest datasets. A request might look like:

GET /api/products?offset=40&limit=20

Before selecting it, confirm the following:

  • The endpoint has a deterministic ORDER BY clause. Do not rely on the database’s unspecified default order.
  • The API enforces a maximum limit and applies a safe default when the client omits it.
  • The response documents whether offset is zero-based.
  • The query remains acceptable when a client requests a deep offset.
  • The UI can tolerate records appearing or disappearing between page requests.

A basic response can include both the returned items and navigation metadata:

{
  "items": [
    { "id": 41, "name": "Example product" }
  ],
  "pagination": {
    "offset": 40,
    "limit": 20,
    "hasMore": true
  }
}

Choose cursor pagination for changing collections

Cursor pagination replaces a visible offset with a token generated by the server. The client follows the continuation supplied in the response:

GET /api/events?limit=25&cursor=eyJvcmRlciI6...

Use a cursor when the collection changes frequently or when clients normally move forward one page at a time. The response should make the next request explicit:

{
  "items": [
    { "id": "evt_1001", "createdAt": "2026-10-12T09:30:00Z" }
  ],
  "next": {
    "href": "/api/events?limit=25&cursor=eyJvcmRlciI6...",
    "cursor": "eyJvcmRlciI6..."
  }
}

For a reliable cursor implementation, check that the token is opaque to clients, tied to the intended sort order, validated before use, and handled safely when it is malformed or no longer usable. A cursor should not silently change the meaning of the query. Decide whether filters and sort parameters must remain identical across requests, and return a clear client error when they do not.

Choose keyset pagination for large, ordered tables

Keyset pagination uses the last item from the current page as the boundary for the next query. For descending creation time with a unique ID tie-breaker, the conceptual query is:

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

The exact syntax varies by database, but the principle is consistent: filter by the last seen sort key rather than skipping a growing number of rows. Always include a unique tie-breaker. Sorting only by a timestamp can produce duplicates or omissions when several records share the same timestamp.

Keyset pagination is a strong choice for feeds and large tables, but it does not naturally support arbitrary page numbers. Explain that limitation in the API documentation instead of adding an unreliable page-count abstraction.

Build the client around continuation, not page arithmetic

Client code should treat pagination as a sequence of server-provided instructions. Follow the next link or cursor returned by the API rather than constructing the next URL by guessing. Stop when the server indicates there is no next page, the continuation link is absent, or the returned item count is zero according to the API contract.

  • Preserve the server’s next URL exactly when practical.
  • Set a client-side maximum page count or item count for batch jobs.
  • Deduplicate records by stable ID when merging pages.
  • Retry transient failures without assuming the failed page can be skipped.
  • Record the request URL and response metadata when diagnosing missing records.

What to double-check

Ordering: Every page must use a stable, documented order. For compound ordering, apply the same fields and directions in the filter used to find the next page.

Consistency expectations: Decide whether the endpoint offers a live view, best-effort traversal, or a snapshot-like experience. Cursor and keyset designs reduce shifting caused by inserts, but they do not automatically freeze the dataset.

Deleted records: If a record disappears after a client receives it, the client should generally continue from the returned continuation rather than trying to reconstruct a page number.

Updated sort keys: A record whose ordering field changes during traversal may appear in a different position. If this matters, use a suitable snapshot or immutable traversal key and document the behavior.

Database indexes: Inspect the query plan for the actual filter and order combination. An index that supports filtering but not ordering may still leave the database sorting a large result set. For deeper performance investigation, the Browser DevTools performance workflow can help separate API latency from client-side rendering time, while the SQL query review guide is useful when inspecting complex pagination queries.

HTTP behavior: Define responses for invalid limits, malformed cursors, unsupported sort fields, and expired or incompatible tokens. Use the API’s established error format consistently; the HTTP status code reference provides a practical debugging companion.

Common mistakes

  • Returning an unbounded page: A client-supplied limit should never be trusted without validation and a server maximum.
  • Using offset without stable ordering: Results can move unpredictably between requests, making duplicates and omissions difficult to explain.
  • Sorting by a non-unique field: Add a unique tie-breaker to keyset and cursor queries.
  • Exposing internal cursor structure: Treat cursors as opaque. Clients should not parse database IDs, timestamps, or implementation details from them.
  • Changing filters while continuing: A next cursor generated for one filter or sort order may be invalid for another.
  • Assuming retries are harmless: A retry can duplicate work or records in a client accumulator. Make merging idempotent by stable identifier.
  • Testing only static data: Insert, delete, and update records while a test client walks through multiple pages.

For a broader troubleshooting process, pair pagination tests with the API debugging runbook. Capture the request parameters, response order, continuation value, database query, and timing for each page.

When to revisit

Review a pagination design before a seasonal planning cycle, a major data-volume increase, or a change to the endpoint’s filters and sort options. Revisit it when schema changes, index changes, database upgrades, framework upgrades, or a new client use case alter the query pattern. A design that works for a small internal table may need keyset or cursor pagination when it becomes a high-volume feed.

Use this action checklist during review:

  1. Record the endpoint’s intended ordering, page-size limits, and consistency promise.
  2. Test first, middle, and deep traversal paths with realistic data.
  3. Run concurrent insert, update, and delete tests while a client fetches pages.
  4. Verify that indexes support both the pagination filter and ordering.
  5. Test invalid, repeated, expired, and reused continuation values.
  6. Confirm that clients follow next links, cap total work, deduplicate results, and retry safely.
  7. Update API documentation and examples whenever response fields or continuation rules change.

As a practical rule, use offset when straightforward page navigation matters and the dataset is manageable; use cursor when the API must hide continuation details and handle changing data; and use keyset when efficient traversal over a large, consistently ordered table is the priority. Recheck that decision whenever the data, query, or client workflow changes.

Related Topics

#rest-api#pagination#databases#backend#api-design
C

CodeGuru Editorial Team

Developer Resources Editor

Senior editor and content strategist. Writing about technology, design, and the future of digital media. Follow along for deep dives into the industry's moving parts.