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.
| Pattern | Best fit | Main advantage | Main trade-off |
|---|---|---|---|
| Offset | Small, relatively stable datasets and page-number interfaces | Simple to understand and debug | Deep pages can become slower and shift when rows change |
| Cursor | Feeds, timelines, and APIs with changing data | Stable continuation without exposing sort details | Tokens need validation, expiry rules, and clear client handling |
| Keyset | Large tables with a suitable indexed ordering | Efficient traversal of deep result sets | Requires 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 BYclause. Do not rely on the database’s unspecified default order. - The API enforces a maximum
limitand applies a safe default when the client omits it. - The response documents whether
offsetis 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:
- Record the endpoint’s intended ordering, page-size limits, and consistency promise.
- Test first, middle, and deep traversal paths with realistic data.
- Run concurrent insert, update, and delete tests while a client fetches pages.
- Verify that indexes support both the pagination filter and ordering.
- Test invalid, repeated, expired, and reused continuation values.
- Confirm that clients follow next links, cap total work, deduplicate results, and retry safely.
- 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.