API Pagination Design: Offset vs Cursor-based Pagination

API Pagination Design

Offset-based Pagination

GET /api/posts?offset=20&limit=10

✅ Simple, supports jumping to any page ❌ Poor performance on large datasets (OFFSET N scans N rows) ❌ Data added/deleted causes missing or duplicate items

Cursor-based Pagination (recommended)

GET /api/posts?cursor=eyJpZCI6MTAwfQ&limit=10

Cursor is typically the last item ID or timestamp (Base64-encoded)

✅ Consistent performance regardless of dataset size ✅ No data loss or duplication with real-time data ❌ Cannot jump to arbitrary pages (next/prev only)

Keyset Pagination (cursor variant)

GET /api/posts?after_id=100&limit=10

Filters using indexed columns (ID, created_at) for efficient SQL queries

Decision Guide

Use Case	Recommendation
Admin lists, page jumping needed	Offset
Feed, timeline, infinite scroll	Cursor / Keyset
Large dataset API	Cursor / Keyset

Response Format (cursor example)

{ data: [...], next_cursor: "...", has_more: true }