Browse cheat sheets · APIs
API Pagination Patterns
Design and consume paginated APIs safely using offset, page-number, cursor, keyset, and continuation-token patterns with clear ordering, stable traversal, and production-safe client behavior.
On this page
- Problem
- Quick answer
- Code / commands
- 1. Limit-only pagination
- 2. Offset pagination
- 3. Page-number pagination
- 4. Return pagination metadata
- 5. Be cautious with total counts
- 6. Cursor pagination
- 7. Make cursors opaque to clients
- 8. Cursor contents may encode ordering state
- 9. Keyset pagination
- 10. Use a deterministic tie-breaker
- 11. Match keyset predicate to sort direction
- 12. Composite keyset pagination
- 13. Do not expose database row offsets as a stable business cursor
- 14. Offset pagination can skip rows during concurrent inserts
- 15. Offset pagination can duplicate rows during deletes
- 16. Keyset pagination is usually more stable for forward traversal
- 17. Cursor pagination does not automatically create a snapshot
- 18. Add a stable upper bound for long traversals
- 19. Continuation-token pagination
- 20. Continuation tokens may expire
- 21. Bind cursors to the original query shape
- 22. Encode filter/sort identity in opaque cursors when useful
- 23. Sign cursors when clients must not tamper with them
- 24. Encrypt cursors only when confidentiality is needed
- 25. Validate page size
- 26. Clamp or reject oversized page requests
- 27. Do not silently change page size without telling the client
- 28. Preserve filters across pages
- 29. Preserve sort order across pages
- 30. Paginate after filtering, not before
- 31. Paginate a stable business grain
- 32. Avoid paginating a non-deterministic query
- 33. Never rely on physical database row order
- 34. Use unique ordering for backward pagination too
- 35. Example forward cursor response
- 36. Example backward-capable page info
- 37. Link-based pagination
- 38. HTTP Link header pagination
- 39. Client loop for cursor pagination
- 40. Do not stop based only on page length
- 41. Offset client loop
- 42. Retry a page without advancing state
- 43. Make page processing idempotent when possible
- 44. Do not assume exactly-once delivery from pagination
- 45. Checkpoint the continuation token only after durable processing
- 46. Store cursor checkpoints with query identity
- 47. Cursor expiry requires restart strategy
- 48. Use watermarks for incremental synchronization
- 49. Add a tie-breaker to watermark sync
- 50. Use half-open incremental boundaries carefully
- 51. Avoid updated_at > last_timestamp without tie handling
- 52. Offset pagination can become slower at deep offsets
- 53. Keyset pagination works best with matching indexes
- 54. Avoid large joins after pagination if they change row multiplicity
- 55. Avoid pagination after row multiplication
- 56. Return empty final page consistently
- 57. Invalid cursor should be a client error
- 58. Do not expose stack traces when cursor decoding fails
- 59. Rate limits apply across pagination
- 60. Sequential cursor chains are often inherently sequential
- 61. Parallelize by partition, not by guessed cursor
- 62. Page size affects throughput and failure cost
- 63. Compress large paginated responses
- 64. Limit fields when supported
- 65. Avoid returning giant nested collections inside each paginated item
- 66. Pagination and sorting must be compatible
- 67. Reject unsupported sort fields
- 68. Validate pagination numeric inputs
- 69. Avoid integer overflow in offset calculation
- 70. Use stable default ordering
- 71. Consider deletion behavior
- 72. Consider updates to sort keys
- 73. Prefer immutable monotonic keys for stream-like feeds
- 74. UUIDs are unique but not necessarily useful ordering keys
- 75. Pagination is not a substitute for bulk export
- 76. Use 202 for asynchronous export creation
- 77. Document page consistency
- 78. Document cursor lifecycle
- 79. Monitor pagination behavior
- 80. Detect pathological offset usage
- What the result means
- What to look for
- Duplicate records across pages
- Missing records
- Deep pages get slower
- Cursor suddenly becomes invalid
- Client loops forever
- Client stops early
- Production notes
- Pagination semantics are part of the API contract
- Deterministic ordering is mandatory
- Cursor values should generally be opaque
- Pagination does not guarantee snapshot consistency
- Retries and checkpointing matter
- Bulk extraction may need a different API
- Common mistakes
- 1. Paginating without ORDER BY
- 2. Ordering only by a non-unique timestamp
- 3. Using offset pagination for huge mutable datasets by default
- 4. Assuming cursor pagination creates a snapshot
- 5. Letting clients choose unlimited page size
- 6. Advancing the cursor before page processing is durable
- 7. Assuming short pages mean end-of-data
- 8. Reusing a cursor with different filters or sorting
- 9. Returning exact total counts when they are too expensive
- 10. Using pagination for massive data export
- Next step
- Related deep dives
Problem
An API endpoint can return too much data to send in one response.
Pagination solves the transport problem, but production issues appear when engineers do not define:
- ordering
- page boundaries
- behavior while data changes
- continuation semantics
- maximum page size
- retry behavior
- duplicate and missing-row handling
- how clients know when they are done
The goal is to choose a pagination model that matches the data and to make traversal predictable for both API producers and consumers.
Quick answer
Use this decision model:
Small/simple admin API
→ page number or offset can be enough
Large ordered dataset
→ cursor or keyset pagination
Rapidly changing dataset
→ cursor/keyset with deterministic ordering
Backend/provider already returns continuation tokens
→ expose or wrap continuation-token semantics
Need random access to "page 57"
→ page/offset pagination
Need efficient sequential traversal
→ cursor/keyset pagination
Simple offset example:
GET /v1/orders?limit=100&offset=200
Cursor example:
GET /v1/orders?limit=100&after=eyJpZCI6MTIzNDU2fQ
Keyset example:
GET /v1/orders?limit=100&after_created_at=2026-10-04T14:00:00Z&after_id=123456
The most important rule is:
pagination requires deterministic ordering
Code / commands
1. Limit-only pagination
Example:
GET /v1/orders?limit=100
This is incomplete unless the API also defines:
- ordering
- continuation mechanism
- maximum limit
A limit alone is not a full pagination contract.
2. Offset pagination
GET /v1/orders?limit=100&offset=200
Equivalent SQL shape:
SELECT
order_id,
created_at,
amount
FROM dbo.orders
ORDER BY created_at, order_id
OFFSET 200 ROWS
FETCH NEXT 100 ROWS ONLY;
Use when:
- data volume is moderate
- random page access matters
- dataset mutation during traversal is not a major concern
3. Page-number pagination
GET /v1/orders?page=3&pageSize=100
Server typically converts:
offset = (page - 1) * pageSize
This is easy for clients to understand.
It has the same fundamental consistency/performance limitations as offset pagination.
4. Return pagination metadata
Example response:
{
"items": [
{
"orderId": 123
}
],
"page": 3,
"pageSize": 100,
"hasNext": true
}
Only return totalCount when you can compute it at acceptable cost and the semantics are clear.
5. Be cautious with total counts
This pattern:
{
"totalCount": 98765432
}
may require an expensive count over the full filtered dataset.
Do not promise an exact total if generating it makes every request expensive.
Alternatives:
hasNext
nextCursor
approximateCount
count returned by a separate endpoint
if appropriate to the product.
6. Cursor pagination
Request:
GET /v1/orders?limit=100&after=opaque-cursor-value
Response:
{
"items": [
{
"orderId": 123
}
],
"nextCursor": "opaque-cursor-value-2",
"hasNext": true
}
Use when clients mainly move forward sequentially.
7. Make cursors opaque to clients
Prefer:
after=eyJjcmVhdGVkQXQiOiIyMDI2LTEwLTA0VDE0OjAwOjAwWiIsImlkIjoxMjM0NTZ9
over requiring the client to understand internal storage keys.
An opaque cursor gives the server room to change implementation later.
8. Cursor contents may encode ordering state
Conceptually, a cursor might represent:
{
"createdAt": "2026-10-04T14:00:00Z",
"orderId": 123456
}
The client should treat it as opaque.
The server can encode/sign it as appropriate.
9. Keyset pagination
Request:
GET /v1/orders?limit=100&afterCreatedAt=2026-10-04T14:00:00Z&afterId=123456
SQL-style condition:
WHERE
created_at > @after_created_at
OR (
created_at = @after_created_at
AND order_id > @after_id
)
ORDER BY
created_at,
order_id
This avoids scanning and discarding a large offset.
10. Use a deterministic tie-breaker
Bad:
ORDER BY created_at
if many rows share the same timestamp.
Better:
ORDER BY
created_at,
order_id
The last ordering column should make row order deterministic.
11. Match keyset predicate to sort direction
Ascending:
WHERE
created_at > @last_created_at
OR (
created_at = @last_created_at
AND order_id > @last_order_id
)
ORDER BY
created_at ASC,
order_id ASC
Descending:
WHERE
created_at < @last_created_at
OR (
created_at = @last_created_at
AND order_id < @last_order_id
)
ORDER BY
created_at DESC,
order_id DESC
The comparison operators must match the requested sort direction.
12. Composite keyset pagination
If order is:
tenant_id
created_at
order_id
the continuation predicate must preserve the same lexicographic ordering.
Do not paginate using only part of the ordering key.
13. Do not expose database row offsets as a stable business cursor
Offsets identify a position in one result ordering at one moment.
They are not stable identifiers.
If rows are inserted or removed, later offsets can shift.
14. Offset pagination can skip rows during concurrent inserts
Example:
Page 1:
rows 1–100
new row inserted near the beginning
Page 2:
OFFSET 100
The client may see:
- a duplicate row
- a skipped row
depending on how ordering shifted.
15. Offset pagination can duplicate rows during deletes
If earlier rows disappear between requests, offsets shift backward.
This can cause the next request to overlap previously returned rows.
This is expected behavior for mutable datasets.
16. Keyset pagination is usually more stable for forward traversal
If the cursor represents the last seen ordered key:
created_at + order_id
new rows inserted before that key do not normally shift the continuation point.
This makes cursor/keyset pagination attractive for mutable datasets.
17. Cursor pagination does not automatically create a snapshot
Even with cursors, the underlying data may change between requests.
If strict snapshot semantics are required, you need an explicit design such as:
- snapshot/version identifier
- fixed upper bound
- database snapshot/transaction semantics
- exported result set
Do not promise snapshot consistency unless the backend actually provides it.
18. Add a stable upper bound for long traversals
Example first request:
GET /v1/events?limit=100
Server may establish:
snapshotMaxId = 9000000
Subsequent traversal can enforce:
event_id <= 9000000
This prevents new events from extending the dataset indefinitely during the same traversal.
Only use this if it matches the product semantics.
19. Continuation-token pagination
Some services return an opaque provider-generated token:
{
"items": [...],
"continuationToken": "abc123"
}
Next request:
GET /v1/items?continuationToken=abc123
Treat the token as opaque.
Do not parse or modify it unless the provider explicitly documents its structure.
20. Continuation tokens may expire
Document whether a token is:
- short-lived
- reusable
- single-use
- bound to filters
- bound to caller identity
Clients should not assume a continuation token works forever.
21. Bind cursors to the original query shape
If a cursor was generated for:
status=active
sort=created_at
do not let the client reuse it with:
status=closed
sort=name
The server should reject or ignore incompatible cursor/query combinations.
22. Encode filter/sort identity in opaque cursors when useful
Conceptually:
{
"sort": "created_at,id",
"filtersHash": "abc123",
"lastCreatedAt": "...",
"lastId": 123
}
This can prevent misuse of a cursor with a different query.
Do not expose sensitive filter values unnecessarily.
23. Sign cursors when clients must not tamper with them
A server-controlled cursor can be:
payload
+
integrity signature
so modified cursor contents are rejected.
Do not rely on Base64 encoding as tamper protection.
Encoding is not signing.
24. Encrypt cursors only when confidentiality is needed
If cursor contents contain internal identifiers or sensitive state that should not be visible, encryption may be appropriate.
If confidentiality is not needed, signed opaque encoding may be enough.
Use established crypto libraries/frameworks.
25. Validate page size
Example policy:
default = 100
max = 1000
Do not assume these numbers are universally correct.
Choose values based on:
- row width
- backend cost
- latency
- client behavior
- rate limits
26. Clamp or reject oversized page requests
Example:
GET /v1/orders?limit=1000000
The API should not blindly honor arbitrary page sizes.
Either:
reject with validation error
or:
cap to documented maximum
Be consistent.
27. Do not silently change page size without telling the client
If the client asks for:
limit=1000
and the server caps at:
500
make the actual page size visible in:
- response metadata
- documentation
- headers
so the client can reason correctly.
28. Preserve filters across pages
Client code must send the same filter set for every page.
Bad:
Page 1:
status=active
Page 2:
status omitted
This changes the result set mid-traversal.
29. Preserve sort order across pages
A cursor generated under:
sort=created_at
must not be reused under:
sort=name
Ordering is part of the pagination state.
30. Paginate after filtering, not before
Correct conceptual order:
filter
→ sort
→ paginate
Not:
paginate
→ filter
Otherwise page sizes and traversal semantics become wrong.
31. Paginate a stable business grain
If a join produces multiple rows per order but the API promises one order per item, deduplicate/aggregate to the intended order grain before pagination.
Do not paginate an accidental intermediate grain.
32. Avoid paginating a non-deterministic query
Bad SQL:
SELECT *
FROM dbo.orders
OFFSET 0 ROWS
FETCH NEXT 100 ROWS ONLY;
without ORDER BY.
Pagination requires stable ordering.
33. Never rely on physical database row order
A database table has no guaranteed natural order unless the query specifies one.
Always define ORDER BY.
34. Use unique ordering for backward pagination too
If supporting:
before=<cursor>
the server must invert the continuation predicate correctly and still return items in the documented display order.
Backward pagination is more complex than simply replacing > with <.
35. Example forward cursor response
{
"items": [
{
"orderId": 123,
"createdAt": "2026-10-04T14:00:00Z"
}
],
"pageInfo": {
"hasNextPage": true,
"nextCursor": "opaque-token"
}
}
Keep metadata names consistent across endpoints.
36. Example backward-capable page info
{
"items": [...],
"pageInfo": {
"hasNextPage": true,
"hasPreviousPage": true,
"nextCursor": "next-token",
"previousCursor": "previous-token"
}
}
Only expose backward traversal if the implementation supports it correctly.
37. Link-based pagination
An API can return URLs directly:
{
"items": [...],
"links": {
"next": "https://api.example.com/v1/orders?cursor=abc",
"prev": null
}
}
This reduces the amount of URL-building logic required by clients.
38. HTTP Link header pagination
Example:
Link: <https://api.example.com/v1/orders?cursor=abc>; rel="next"
This is valid and useful in some APIs.
Do not require clients to parse both body pagination and Link headers unless there is a clear reason.
39. Client loop for cursor pagination
Python example:
import requests
url = "https://api.example.com/v1/orders"
cursor = None
while True:
params = {
"limit": 100
}
if cursor:
params["after"] = cursor
response = requests.get(
url,
params=params,
timeout=30,
)
response.raise_for_status()
payload = response.json()
for item in payload["items"]:
process(item)
cursor = payload.get("nextCursor")
if not cursor:
break
In production, add retry, auth, logging, and idempotent processing as appropriate.
40. Do not stop based only on page length
Bad client logic:
if len(items) < page_size:
break
This can fail if the API:
- filters internally
- caps results dynamically
- returns sparse pages
- uses provider-side continuation
Prefer explicit:
nextCursor
hasNext
nextLink
from the API contract.
41. Offset client loop
import requests
offset = 0
limit = 100
while True:
response = requests.get(
"https://api.example.com/v1/orders",
params={
"offset": offset,
"limit": limit,
},
timeout=30,
)
response.raise_for_status()
payload = response.json()
items = payload["items"]
for item in items:
process(item)
if not payload.get("hasNext"):
break
offset += limit
Use only if the API guarantees this pagination model.
42. Retry a page without advancing state
Correct client behavior:
request page
→ failure
→ retry same page/cursor
→ success
→ process safely
→ advance cursor
Do not advance the continuation token before the page has been handled successfully.
43. Make page processing idempotent when possible
If the client crashes after processing half a page and retries that page, records may be seen again.
Design processing so duplicate delivery does not corrupt downstream state.
Examples:
- upsert by business key
- checkpoint after durable processing
- deduplicate by event ID
44. Do not assume exactly-once delivery from pagination
Pagination is a retrieval mechanism.
It does not guarantee that a client will observe each mutable record exactly once across crashes, retries, or concurrent changes.
If exactly-once-like business behavior matters, add durable state and idempotency.
45. Checkpoint the continuation token only after durable processing
Bad:
save nextCursor
→ process page
→ crash
The page may be skipped after restart.
Safer:
fetch page
→ process page durably
→ save nextCursor/checkpoint
46. Store cursor checkpoints with query identity
Checkpoint:
{
"endpoint": "/v1/orders",
"filters": {
"status": "active"
},
"cursor": "opaque-token"
}
Do not reuse a stored cursor for a different query shape.
47. Cursor expiry requires restart strategy
If cursors can expire, clients should know whether to:
- restart traversal
- restart from last processed business key
- request a fresh export
- use a durable watermark instead
Document this behavior.
48. Use watermarks for incremental synchronization
Example:
updated_at > last_successful_watermark
Pagination and incremental loading solve different problems.
A robust sync often combines:
incremental filter
+
deterministic pagination
49. Add a tie-breaker to watermark sync
Bad:
updated_at > 2026-10-04T14:00:00Z
if many rows share that timestamp.
Better continuation state:
updated_at
+
id
and keyset semantics.
50. Use half-open incremental boundaries carefully
A common pattern is:
start inclusive
end exclusive
Example:
updated_at >= start
AND updated_at < end
This can simplify adjacent batch boundaries.
For paginated incremental sync, still define deterministic row ordering within the window.
51. Avoid updated_at > last_timestamp without tie handling
If several records have:
updated_at = last_timestamp
some can be skipped after restart.
Store enough state to distinguish rows sharing the same timestamp.
52. Offset pagination can become slower at deep offsets
Conceptually:
OFFSET 10
→ cheap-ish
OFFSET 10,000,000
→ database may still need to locate/scan/sort past many rows
Exact behavior depends on database/index/query plan.
Do not assume constant-time page access.
53. Keyset pagination works best with matching indexes
For:
ORDER BY created_at, order_id
a useful index often starts with compatible ordering/filter columns.
Index design depends on:
- filters
- selectivity
- included columns
- database engine
Do not add an index blindly only because pagination exists.
54. Avoid large joins after pagination if they change row multiplicity
Problematic conceptual flow:
paginate orders
→ join order_lines
→ result now has multiple rows per order
If the API contract is one order per item, enrich carefully or aggregate lines separately.
55. Avoid pagination after row multiplication
If a join accidentally creates duplicates before pagination, page boundaries become unstable and counts become misleading.
Validate grain before paginating.
56. Return empty final page consistently
If a cursor explicitly requests beyond the end, choose documented behavior such as:
{
"items": [],
"nextCursor": null,
"hasNext": false
}
Do not randomly alternate between empty 200 and 404.
57. Invalid cursor should be a client error
If a cursor is malformed, tampered with, expired, or incompatible with the request, return a clear client-facing error.
Example:
HTTP/1.1 400 Bad Request
{
"error": "invalid_cursor",
"message": "The pagination cursor is invalid or expired."
}
Exact status/error model should be consistent with the API.
58. Do not expose stack traces when cursor decoding fails
Malformed cursors are client input, not an excuse to leak internal parsing/crypto details.
Return a stable domain error.
59. Rate limits apply across pagination
Clients may fetch hundreds of pages.
Respect:
429Retry-After- per-client quotas
- concurrency limits
Do not parallelize every page request automatically.
60. Sequential cursor chains are often inherently sequential
If page N+1 requires the cursor from page N:
page 1
→ cursor 2
→ page 2
→ cursor 3
you cannot safely request all pages in parallel unless the API exposes independent partitions/ranges.
61. Parallelize by partition, not by guessed cursor
If the API supports partitioning such as:
tenant
date range
shard
partition key
clients can process independent partitions concurrently.
Do not fabricate future cursor values.
62. Page size affects throughput and failure cost
Larger pages:
fewer HTTP requests
larger payloads
more retry work if one page fails
more memory per response
Smaller pages:
more requests
more per-request overhead
smaller retry unit
Choose based on real workload characteristics.
63. Compress large paginated responses
If supported, clients can send:
Accept-Encoding: gzip
or use:
curl --compressed ...
This can reduce transfer size for text-heavy JSON.
64. Limit fields when supported
Example:
GET /v1/orders?fields=orderId,createdAt,amount&limit=100
Reducing row width can improve pagination throughput.
Only expose field projection if your API contract supports it safely.
65. Avoid returning giant nested collections inside each paginated item
Example:
100 orders
×
thousands of nested line items
can defeat pagination.
Consider:
- separate child endpoints
- summaries
- bounded expansions
- explicit include parameters
66. Pagination and sorting must be compatible
If clients can sort by arbitrary columns:
?sort=name
the server needs a deterministic tie-breaker for every supported sort.
Example:
sort=name
effective order:
name, id
67. Reject unsupported sort fields
Do not interpolate arbitrary client-provided sort expressions directly into SQL.
Whitelist supported fields and directions.
This is both a correctness and security concern.
68. Validate pagination numeric inputs
Example invalid requests:
limit=-1
offset=-50
page=0
pageSize=999999999
Return a controlled validation error.
Do not let invalid values reach storage code unchecked.
69. Avoid integer overflow in offset calculation
For page-number APIs:
offset = (page - 1) * pageSize
validate bounds before calculating/executing very large values.
This matters especially in strongly typed server languages and large public APIs.
70. Use stable default ordering
If the client does not specify sort order, document the server default.
Example:
created_at DESC, id DESC
Do not change the default ordering silently between releases.
71. Consider deletion behavior
With keyset pagination:
last seen key
→ continue after that key
deleting an earlier row normally does not shift the cursor.
With offset pagination, deletion can shift subsequent positions.
This is one reason keyset pagination is often more stable for mutable data.
72. Consider updates to sort keys
If a row’s ordering column changes while the client is traversing, it may move:
before the cursor
or
after the cursor
and could be missed or observed twice.
If this matters, use:
- immutable sort key
- snapshot bound
- append-only sequence
- dedicated sync/change-feed design
73. Prefer immutable monotonic keys for stream-like feeds
Examples:
event_id
sequence_number
commit_position
when available.
These simplify keyset traversal and checkpointing.
Do not invent monotonic semantics for identifiers that are not actually ordered.
74. UUIDs are unique but not necessarily useful ordering keys
A random UUID can be an excellent unique identifier but a poor chronological pagination key.
Use it as a tie-breaker if needed, not as a replacement for meaningful ordering unless its ordering semantics are deliberate.
75. Pagination is not a substitute for bulk export
If a client needs:
hundreds of millions of rows
consider:
- asynchronous export job
- file delivery
- object storage
- data-sharing mechanism
rather than forcing millions of API page calls.
76. Use 202 for asynchronous export creation
Example:
POST /v1/exports
Response:
HTTP/1.1 202 Accepted
Location: /v1/exports/job-123
Then the client can poll or receive notification when the export is ready.
77. Document page consistency
Tell clients whether pagination is:
best-effort over live data
snapshot-consistent
bounded by first-request watermark
eventually consistent
Do not leave mutation behavior undefined for critical integrations.
78. Document cursor lifecycle
Include:
opaque?
expiry?
reusable?
filter-bound?
caller-bound?
forward-only?
This prevents clients from building unsafe assumptions.
79. Monitor pagination behavior
Useful metrics:
requests by endpoint
page size
deepest offset
pages per traversal
cursor errors
429 rate
response bytes
latency by page size
This can reveal clients abusing large offsets or fetching entire datasets inefficiently.
80. Detect pathological offset usage
Example:
offset=50,000,000
may indicate the client is using a list endpoint as a bulk export mechanism.
Consider a cursor or export API instead.
What the result means
| Pattern | Strength | Weakness |
|---|---|---|
| Page number | Easy for humans/UI | Same deep-offset and mutation issues as offset |
| Offset + limit | Simple, supports random access | Can become slow and unstable on changing datasets |
| Cursor | Stable API abstraction | Usually sequential; token lifecycle must be defined |
| Keyset | Efficient/stable forward traversal | Harder random access; requires deterministic key |
| Continuation token | Works well with provider/backend-native paging | Often opaque/provider-specific |
| Snapshot + cursor | Strong traversal consistency | More backend complexity/state |
| Async export | Best for very large retrievals | Not interactive page browsing |
The central design choice is:
random page access
vs
stable efficient traversal
What to look for
Duplicate records across pages
Check:
- offset pagination over changing data
- non-unique ordering
- sort-key updates
- retry behavior
Missing records
Check:
- cursor predicate
- timestamp ties
- unstable ordering
- checkpoint timing
- filter changes between requests
Deep pages get slower
Offset pagination may be scanning/skipping increasingly large prefixes.
Inspect query plans and consider keyset pagination.
Cursor suddenly becomes invalid
Check:
- expiry
- filter/sort changes
- token signing keys
- backend/provider continuation rules
Client loops forever
Check:
- repeated same cursor
hasNextlogic- server returning non-advancing continuation tokens
- client not checkpointing the new cursor
Client stops early
Check whether it incorrectly assumes:
items.length < requested page size
means the end.
Prefer explicit continuation metadata.
Production notes
Pagination semantics are part of the API contract
Changing:
default sort
cursor structure
page-size cap
continuation behavior
can break clients.
Treat these as versioned behavior.
Deterministic ordering is mandatory
Every paginated result needs a complete ordering.
If the visible sort column is not unique, add a tie-breaker.
Cursor values should generally be opaque
This reduces client coupling to internal storage keys and lets the implementation evolve.
Pagination does not guarantee snapshot consistency
If strict consistency matters, implement it explicitly.
Retries and checkpointing matter
A robust client should be able to retry one page without:
- skipping data
- corrupting downstream state
Bulk extraction may need a different API
Pagination is ideal for bounded interactive traversal, not always for warehouse-scale export.
Common mistakes
1. Paginating without ORDER BY
Database row order is not guaranteed.
2. Ordering only by a non-unique timestamp
Rows with equal timestamps can move across boundaries.
3. Using offset pagination for huge mutable datasets by default
Deep offsets and row movement become problematic.
4. Assuming cursor pagination creates a snapshot
It does not unless explicitly designed that way.
5. Letting clients choose unlimited page size
One request can become a bulk export.
6. Advancing the cursor before page processing is durable
A crash can skip records.
7. Assuming short pages mean end-of-data
Use explicit continuation metadata.
8. Reusing a cursor with different filters or sorting
The cursor may no longer represent the same result set.
9. Returning exact total counts when they are too expensive
Do not make every page request pay for a full count unless the product truly needs it.
10. Using pagination for massive data export
Use an asynchronous export/data-sharing pattern when the scale demands it.
Was this helpful?
What could be better?
Thanks — that helps me improve Javi Builds.
Stay in the loop
Get the Javi Builds updates you actually care about.
Check your inbox
I sent you a confirmation link. Your subscription will be active after you confirm it.