What is a Cursor

A cursor is an opaque token that represents a position in a paginated result set. The server returns a cursor with each page. The client sends it back to request the next page: GET /users?after=eyJpZCI6NDJ9&limit=50.

How it works

The cursor typically encodes a sort key — for example, base64-encoded {"id": 42}. The server decodes it and uses it as a WHERE clause: WHERE id > 42 ORDER BY id LIMIT 50. Because it points to a specific position in the sorted data, cursors are unaffected by inserts or deletes on previous pages.

The cursor is opaque to the client — the format can change without breaking the API. Clients should never parse or construct cursors.

Why it matters

Cursors solve the problems with offset-based pagination. Offsets skip rows (slow on large datasets) and shift when data changes (unstable). Cursors point to a specific item, so the next page is always correct regardless of concurrent writes. This is why GitHub, Stripe, Slack, and most modern APIs use cursor-based pagination.

See How REST Works for how cursor-based pagination integrates with REST APIs.