# What is Cursor?

Also called Cursor Pagination, Keyset Pagination, Continuation Token.

A cursor is an opaque marker returned with a page of results that tells the server where the next page should begin. Instead of counting a numeric offset, the client passes the cursor back and the server resumes reading immediately after the encoded position. The same idea appears as a continuation token in streaming and event APIs.

Under the hood a cursor usually encodes the sort key values of the last returned row, allowing the database to seek directly to that point using an index rather than scanning and discarding earlier rows. Query cost therefore stays roughly constant regardless of how deep into the result set the client has walked, which is the main advantage over offsets.

Cursors are deliberately opaque. Encoding them as base64 or a signed blob signals that clients must not parse, construct, or increment them, which leaves the provider free to change the internal representation later. Some providers sign cursors so a tampered value is rejected rather than silently reading from an unintended position.

Correctness depends on a total ordering. If the sort key is not unique, ties can cause records to be skipped or repeated at page boundaries, so implementations add a unique tiebreaker such as the primary key. Cursors are also normally tied to the exact query parameters that produced them; changing a filter mid-walk invalidates the marker.

Cursors have a shelf life. Providers commonly expire them after minutes or hours, and a paused job that resumes with a stale cursor must be prepared to restart. The trade off against offsets is that arbitrary page jumps are impossible: cursor pagination moves forward, and sometimes backward, but cannot land on page forty directly.

## Key points

- Opaque marker encoding where the next page starts
- Constant cost regardless of depth, unlike offsets
- Never parse, build, or increment a cursor
- Requires a stable total ordering with a tiebreaker
- Usually expires; no jumping to an arbitrary page

## In practice

An events API returns one hundred events ordered by creation time with the record identifier as tiebreaker, plus a base64 cursor. A synchronization job stores that cursor after each successful batch. When the job restarts hours later it presents the saved cursor; if the provider reports it as expired, the job falls back to a timestamp filter and re-reads a small overlapping window, deduplicating by event identifier.

## Related terms

- [Pagination](/en/glossary/pagination)
- [API](/en/glossary/api)
- [REST API](/en/glossary/rest-api)
- [Idempotency](/en/glossary/idempotency)
- [Long Polling](/en/glossary/long-polling)

[Back to the AI Glossary](/en/glossary)