Pagination
Also known as: Paging, Cursor pagination
Quick definition
Pagination is the API pattern for splitting large result sets into multiple smaller responses, letting clients fetch results page-by-page rather than all at once. Two common styles: offset-based (page 1, page 2) and cursor-based (continue from this token). Cursor-based is preferred for large or growing datasets.
What is pagination?
Pagination is the API pattern of splitting a large query result into multiple smaller responses (pages) that the client fetches sequentially. Without pagination, an API request that would return 10,000 records would either time out, exhaust memory, or overwhelm the network. Pagination caps each response at a manageable size (typically 25-100 records per page) and gives the client a way to fetch the next page when ready.
Most APIs default to a page size of 20-50 records and let the client request more (up to a maximum, often 100). Each paginated response includes either a 'next page token' or 'next page link' that the client uses to fetch subsequent pages. The pattern is universal — every API that returns lists has some form of pagination.
Offset-based vs cursor-based pagination
Two main styles. Offset-based: client requests page=1, page=2, etc., or limit=20&offset=40. Simple to implement and reason about; works fine for small static datasets. Cursor-based: client requests records and gets back a `next_cursor` token; subsequent requests pass the cursor to continue. More complex but better for large or growing datasets — offset-based pagination breaks when records are added or deleted between page fetches (page 2 may show duplicates of page 1, or skip records).
Most modern APIs (Stripe, GitHub, X, Instagram Graph API, CodivUpload) use cursor-based pagination because it's reliable for production-grade datasets that change while the client is iterating. Offset-based is fine for admin tools fetching infrequent reports.
Cursor-based pagination via CodivUpload's REST API
bash
# Fetch the first page of posts
curl https://api.codivupload.com/v1/posts?limit=50 \
-H "Authorization: Bearer cdv_..."
# Response includes:
# {
# "data": [...],
# "next_cursor": "eyJ..."
# }
# Fetch the next page using the cursor
curl "https://api.codivupload.com/v1/posts?limit=50&cursor=eyJ..." \
-H "Authorization: Bearer cdv_..."
# Loop until next_cursor is null:
NEXT_CURSOR=""
while true; do
RESPONSE=$(curl -s "https://api.codivupload.com/v1/posts?limit=50&cursor=$NEXT_CURSOR" \
-H "Authorization: Bearer cdv_...")
NEXT_CURSOR=$(echo "$RESPONSE" | jq -r '.next_cursor // empty')
[ -z "$NEXT_CURSOR" ] && break
doneFrequently asked questions
How big should each page be?+
Most APIs default to 20-50 per page. Going larger reduces total round-trips but increases per-request latency and memory. Page sizes of 100-200 are common; beyond 500 most APIs reject as too large.
What if the dataset changes while I'm paginating?+
Cursor-based pagination handles this gracefully — the cursor encodes a stable position. Offset-based pagination can show duplicates or skip records when the underlying data changes between page fetches.
How do I know when I've reached the last page?+
Cursor-based: when the response's next_cursor is null or absent. Offset-based: when the response returns fewer records than the requested limit, or when the API returns a 'no more pages' indicator.
Cursor pagination on every list endpoint
CodivUpload's API uses cursor-based pagination throughout. SDK clients (TypeScript + Python) handle pagination loops automatically — just iterate the result.
See API docsRelated glossary terms