Skip to content
API Design Learn/Querying, Errors & Contracts
Browsing as a guest. Sign in to save your progress and earn XP as you complete chapters.

Pagination: Cursor vs. Offset

4 min read

You'll learn to

  • -Explain pagination as handing back a large list in small, predictable pages
  • -Watch offset pagination show a post twice when a new one arrives, and cursor pagination avoid it
  • -Build a response envelope that says whether more pages exist, with an opaque cursor

Tip: the highlighter is on - just select any text below to mark it. Use the highlighter button up top to change color or turn it off. Highlights are saved on this device only. Log in to save them to your account instead.

No collection endpoint should return "everything" unbounded. Pagination caps the size of each response and gives clients a predictable way to walk through a large result, a page at a time. The two common approaches, offset and cursor, look similar and behave very differently once new data keeps arriving.

An Analogy: A Bookmark vs. a Page Number

Reading a long, growing list is like reading a stack of papers where new sheets keep being added on top. If you remember "I was on the fourth sheet" (an offset), then a new sheet on top pushes everything down and you read one sheet twice. If you put a bookmark on the exact sheet you finished (a cursor), new sheets on top do not matter, and you continue from your bookmark.

Offset Pagination: Simple, With a Real Bug

Offset pagination - simple, but page 2 can skip or repeat rows
GET /orders?limit=20&offset=0     # first 20 orders
GET /orders?limit=20&offset=20    # next 20 orders

Offset pagination is trivial to build and lets a client jump straight to "page 5". But if a row is inserted before the current position while the client is paging, every later page shifts by one. The client then skips an item or sees one twice. On a slow-changing admin table that rarely matters. On a live feed with constant writes, it is a visible bug.

Cursor Pagination: Stable When Data Changes

Cursor pagination - stable regardless of concurrent inserts
GET /orders?limit=20
HTTP/1.1 200 OK
{
  "data": [ /* 20 orders */ ],
  "next_cursor": "eyJpZCI6MTIwfQ==",
  "has_more": true
}

# the client passes the returned cursor to get the next page:
GET /orders?limit=20&cursor=eyJpZCI6MTIwfQ==

A cursor encodes a stable position, usually the last item's sort key such as its id or timestamp, and is often base64-encoded so clients treat it as an opaque token. The next page is defined as "after this item", not "skip N rows", so an insertion elsewhere does not shift what comes next. The trade-off is that a client can no longer jump to page 5 without walking the pages before it.

The demo shows both side by side. A client reads page 1 of ten posts three at a time, then a new post arrives, and the client asks for page 2 each way.

Press Run: offset repeats post 8 after the insert, cursor does not
Offset vs. Cursor, at a Glance
Simple, supports jump-to-page, breaks under concurrent writes
Offset
Stable under writes, no jump-to-page, the standard for feeds/infinite scroll
Cursor

The Response Envelope

Whichever approach you use, the response should say explicitly whether more data exists, with has_more or a next_cursor that is simply null on the last page. Do not make the client guess from getting fewer than limit items back. That guess fails when the total happens to land exactly on a page boundary.

Do not hand out a raw internal id as a "cursor". A token the client can trivially decode and edit is not opaque, and clients will inevitably start relying on its internal structure once they notice it.

Interview Signal

You're designing pagination for a social media feed that receives new posts constantly. The interviewer asks why you'd avoid offset pagination here specifically.

Weak Answer

"Offset pagination is generally worse, so I'd always avoid it."

Strong Answer

"For a feed with constant writes, offset pagination has a real correctness bug: if new posts are inserted while a user scrolls, every post shifts position in the underlying order, so the client can end up seeing the same post twice or skipping one entirely between page loads. Cursor pagination avoids this because each page is defined relative to 'after this specific post,' which stays correct regardless of what gets inserted elsewhere. I wouldn't rule out offset pagination everywhere, though - for a rarely-changing admin table where jump-to-page matters more than write-concurrency correctness, it's still a reasonable choice."

Check Yourself1 / 5

What correctness problem does offset pagination have under concurrent writes?

Ready to Build This?

Design Page Turner in the API Design Lab's REST Foundations act.

Discussion0

Join the Discussion

Sign in to leave comments, reply to others, or like insights.

Sign In to ScaleDojo

No comments yet. Be the first to start the thread!