Currently Available: Need a skilled Software Developer for your next project?
Categories
APIs

Comparing Pagination Types: Offset, Keyset, and Cursor

For a database-backed list, pagination lets a client request results in portions and move from one portion to the next. Offset pagination identifies a position by page number or row count. Keyset pagination continues from the value used to sort the last row. Cursor pagination passes a token that marks a position and that the client sends back.

Offset and keyset describe how the server chooses rows; cursor describes how the client marks its place. A cursor might contain keyset values, an offset, or stand for other state the server stores. Choose offset when people need numbered pages and direct jumps. Choose keyset for efficient sequential browsing through a large list. Use a cursor when a server-defined token gives the API a useful way to pass a position, but check what the token represents before assuming it improves performance or stability.

Offset pagination suits numbered pages

With offset pagination, a client requests a page and the number of items per page. The server skips the rows before that page and returns the requested number. For example, page 3 with 20 items per page means skipping 40 rows and returning the next 20.

This approach makes page numbers and direct jumps straightforward. A user can request a later page without first visiting the earlier pages. The GitHub REST API also illustrates how APIs can expose links for moving between pages.

The database needs a defined sort order so that page boundaries have consistent meaning. Even with an order, deep requests can cost more: the database may need to process many earlier rows before it reaches the requested offset. GitLab’s pagination guidelines describe one PostgreSQL example where a request for page 50,000 at 20 rows per page used an offset of 999,980. The query read 1,000,000 rows to return 20 and took about 5.52 seconds. That result describes one query and workload, not a general latency estimate.

Changes to the list can also shift page contents. If someone inserts or deletes rows before the offset between requests, a later page can contain a repeated row or skip a row the user has not seen. Numbered-page interfaces may also request a total result count to show how many pages exist, and calculating that count can add database work.

Offset is a sensible choice when people need direct page jumps, most requests stay near the beginning, and the database handles the expected result size. Check query plans at the deepest page users are likely to request, and measure the cost of any total-count query.

Keyset pagination follows the last row

Keyset pagination, also called seek pagination, requests rows after or before the last row’s sort value rather than skipping a calculated number of rows. If a list is ordered by increasing ID, the next request can ask for rows where id > last_seen_id, then return a limited number of results.

When the query and indexes support the ordering, the database starts from the last position instead of processing all the rows before it. GitLab’s keyset pagination documentation explains how the sort values mark that position. Keyset works well for feeds, large lists, and interfaces where people move forward or backward rather than jump to a numbered page.

Keyset requests need an order that places every row predictably. If a list sorts by a value that repeats, such as a date, the server should add a unique tie-breaker such as the row ID. Otherwise, the server cannot tell exactly where rows with the same sort value fall at a page boundary. When the sort uses multiple columns, includes values that can be empty, or mixes ascending and descending directions, the server must build conditions that identify which rows come next. It must also use suitable indexes.

Keyset traversal handles inserts or deletes before the current position more predictably than offset traversal because the next request follows a sort value rather than a row number. It does not freeze the list. Rows can still change while someone browses, so exact snapshot behavior depends on the database and application’s consistency rules. Keyset also does not naturally tell a user how to jump to page 100.

A cursor describes a position, not a query plan

A cursor is a value or token that marks a position in a list. The client sends it back to request results before or after that position. The Relay Cursor Connections Specification defines a common GraphQL interface. The interface includes cursors and arguments for moving forward or backward through pages. It also includes page information, such as whether another page exists. The specification describes that interface; database retrieval is outside its scope.

A cursor might encode the sort values used for keyset pagination, or it might represent an offset or server-side state. GitLab’s GraphQL pagination documentation describes both keyset and offset-based approaches in GraphQL. So the word “cursor” alone does not promise efficient deep traversal, stable results, or a fixed snapshot.

An opaque cursor is a token the client should pass back without interpreting its contents. Opaque does not necessarily mean secret or permanent. The API should define how clients handle invalid or expired cursors, and the server should validate incoming tokens. Cursor-based interfaces generally fit next and previous navigation better than arbitrary page numbers. They can also keep clients from having to construct database-specific position values themselves.

Consideration Offset Keyset Cursor API
Position Page number or row offset Last-seen sort value or values Server-provided token or value
Direct jump to a page Natural Requires additional machinery Depends on implementation
Deep-list cost Can rise with page depth Can stay steadier with a matching query and index Depends on what the cursor represents
Changes before the position Can shift later page contents Less affected by earlier inserts or deletes Depends on implementation
Main requirement Defined ordering Deterministic ordering and suitable indexes A clear token design and pagination strategy

Choose for the navigation people need

Choose a method based on how people move through the results. If users need page numbers to jump around a result set, offset pagination supports that directly. If users mainly move through a large list in order, keyset pagination avoids the growing cost of skipping rows at deeper offsets. When an API needs to pass a position between client and server, a cursor provides that interface, but its implementation determines performance and behavior.

Some products need both direct jumps and efficient browsing from one result to the next. A hybrid can provide offset-based page numbers alongside keyset- or cursor-based next and previous navigation, but it makes the implementation and interface more complex. Before choosing this approach, check that users need both forms of navigation and that the API can support them clearly.

The GitLab vulnerability-report discussion shows why pagination alone does not solve every list problem. The issue describes users losing their place after opening a vulnerability, difficulty finding a middle record in a list of 2,500 matches, and concern that an empty page could be mistaken for a completed review. It also raises bulk actions and search as separate needs. Those concerns point to product requirements: preserve list state when users return, make it clear whether more results remain, and state whether a bulk action applies to the current page or all matching records. No pagination method supplies those behaviors automatically.

What I'm building

Delegate tasks. Get software.

Give Vroni a GitHub issue, bug report, spec, or rough idea. It reads the repo, plans the change, writes code, runs checks, and works toward a review-ready pull request.

Take a look at vroni.com

Email updates

Usually a new article and a few links I found interesting.

No spam. Unsubscribe with one click.

Leave a Reply

Your email address will not be published. Required fields are marked *