What is Pagination

Pagination splits large result sets into smaller pages so clients don't download millions of records at once. Instead of returning all 100,000 users, the API returns 50 at a time with a way to request the next page.

How it works

Offset-based: GET /users?offset=100&limit=50 — skip the first 100, return the next 50. Simple but slow on large datasets (the database still scans past skipped rows) and unstable (inserting a row shifts all offsets).

Cursor-based: GET /users?after=abc123&limit=50 — return 50 users after the cursor (an opaque token encoding the position). The server decodes the cursor to a WHERE clause like WHERE id > 42 LIMIT 50. Fast and stable — inserts don't affect other pages.

Keyset: like cursor-based but with transparent parameters: GET /users?created_after=2026-03-24T00:00:00Z&limit=50. The client knows what the cursor means.

Why it matters

Without pagination, a list endpoint that returns thousands of results wastes bandwidth, memory, and time for both client and server. Large unbounded queries can also crash the client or time out the server. Every API that returns collections needs pagination. Cursor-based pagination is the recommended approach for APIs with real-time data or large datasets — it's consistent, performant, and handles concurrent writes gracefully.

See How REST Works for how pagination integrates with REST API design.