Browse cheat sheets · APIs

Technology: APIsCategory: API DesignDifficulty: IntermediateUpdated

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
  1. Problem
  2. Quick answer
  3. Code / commands
  4. 1. Limit-only pagination
  5. 2. Offset pagination
  6. 3. Page-number pagination
  7. 4. Return pagination metadata
  8. 5. Be cautious with total counts
  9. 6. Cursor pagination
  10. 7. Make cursors opaque to clients
  11. 8. Cursor contents may encode ordering state
  12. 9. Keyset pagination
  13. 10. Use a deterministic tie-breaker
  14. 11. Match keyset predicate to sort direction
  15. 12. Composite keyset pagination
  16. 13. Do not expose database row offsets as a stable business cursor
  17. 14. Offset pagination can skip rows during concurrent inserts
  18. 15. Offset pagination can duplicate rows during deletes
  19. 16. Keyset pagination is usually more stable for forward traversal
  20. 17. Cursor pagination does not automatically create a snapshot
  21. 18. Add a stable upper bound for long traversals
  22. 19. Continuation-token pagination
  23. 20. Continuation tokens may expire
  24. 21. Bind cursors to the original query shape
  25. 22. Encode filter/sort identity in opaque cursors when useful
  26. 23. Sign cursors when clients must not tamper with them
  27. 24. Encrypt cursors only when confidentiality is needed
  28. 25. Validate page size
  29. 26. Clamp or reject oversized page requests
  30. 27. Do not silently change page size without telling the client
  31. 28. Preserve filters across pages
  32. 29. Preserve sort order across pages
  33. 30. Paginate after filtering, not before
  34. 31. Paginate a stable business grain
  35. 32. Avoid paginating a non-deterministic query
  36. 33. Never rely on physical database row order
  37. 34. Use unique ordering for backward pagination too
  38. 35. Example forward cursor response
  39. 36. Example backward-capable page info
  40. 37. Link-based pagination
  41. 38. HTTP Link header pagination
  42. 39. Client loop for cursor pagination
  43. 40. Do not stop based only on page length
  44. 41. Offset client loop
  45. 42. Retry a page without advancing state
  46. 43. Make page processing idempotent when possible
  47. 44. Do not assume exactly-once delivery from pagination
  48. 45. Checkpoint the continuation token only after durable processing
  49. 46. Store cursor checkpoints with query identity
  50. 47. Cursor expiry requires restart strategy
  51. 48. Use watermarks for incremental synchronization
  52. 49. Add a tie-breaker to watermark sync
  53. 50. Use half-open incremental boundaries carefully
  54. 51. Avoid updated_at > last_timestamp without tie handling
  55. 52. Offset pagination can become slower at deep offsets
  56. 53. Keyset pagination works best with matching indexes
  57. 54. Avoid large joins after pagination if they change row multiplicity
  58. 55. Avoid pagination after row multiplication
  59. 56. Return empty final page consistently
  60. 57. Invalid cursor should be a client error
  61. 58. Do not expose stack traces when cursor decoding fails
  62. 59. Rate limits apply across pagination
  63. 60. Sequential cursor chains are often inherently sequential
  64. 61. Parallelize by partition, not by guessed cursor
  65. 62. Page size affects throughput and failure cost
  66. 63. Compress large paginated responses
  67. 64. Limit fields when supported
  68. 65. Avoid returning giant nested collections inside each paginated item
  69. 66. Pagination and sorting must be compatible
  70. 67. Reject unsupported sort fields
  71. 68. Validate pagination numeric inputs
  72. 69. Avoid integer overflow in offset calculation
  73. 70. Use stable default ordering
  74. 71. Consider deletion behavior
  75. 72. Consider updates to sort keys
  76. 73. Prefer immutable monotonic keys for stream-like feeds
  77. 74. UUIDs are unique but not necessarily useful ordering keys
  78. 75. Pagination is not a substitute for bulk export
  79. 76. Use 202 for asynchronous export creation
  80. 77. Document page consistency
  81. 78. Document cursor lifecycle
  82. 79. Monitor pagination behavior
  83. 80. Detect pathological offset usage
  84. What the result means
  85. What to look for
  86. Duplicate records across pages
  87. Missing records
  88. Deep pages get slower
  89. Cursor suddenly becomes invalid
  90. Client loops forever
  91. Client stops early
  92. Production notes
  93. Pagination semantics are part of the API contract
  94. Deterministic ordering is mandatory
  95. Cursor values should generally be opaque
  96. Pagination does not guarantee snapshot consistency
  97. Retries and checkpointing matter
  98. Bulk extraction may need a different API
  99. Common mistakes
  100. 1. Paginating without ORDER BY
  101. 2. Ordering only by a non-unique timestamp
  102. 3. Using offset pagination for huge mutable datasets by default
  103. 4. Assuming cursor pagination creates a snapshot
  104. 5. Letting clients choose unlimited page size
  105. 6. Advancing the cursor before page processing is durable
  106. 7. Assuming short pages mean end-of-data
  107. 8. Reusing a cursor with different filters or sorting
  108. 9. Returning exact total counts when they are too expensive
  109. 10. Using pagination for massive data export
  110. Next step
  111. 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.


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.


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:

  • 429
  • Retry-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
  • hasNext logic
  • 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.

Next step

Use the data shape and client need to choose the pattern.

  • Small, stable dataset with random page navigation → page/offset pagination may be sufficient.
  • Large sequential dataset → use cursor/keyset pagination.
  • Dataset changes frequently while clients traverse it → use deterministic keyset/cursor semantics and document consistency.
  • Timestamps are the cursor key → add a unique tie-breaker.
  • Client needs reliable restart → checkpoint only after durable processing.
  • Cursor expires → define restart/watermark behavior.
  • Deep offsets are slow → inspect query plan and move toward keyset pagination.
  • Client needs all data at warehouse scale → design an async export instead of millions of page requests.
  • Pagination results are duplicated or missing → inspect ordering, mutations, continuation predicates, and checkpoint logic.
  • API request itself is failing → move to Troubleshoot API Requests.

← All cheat sheets