API Pagination: Complete Implementation Guide for Production APIs
Pagination is essential for any API that returns lists of data. Without it, your API becomes a bottleneck, potentially crashing your server or slowing down your clients as your dataset grows.
🔐 Securely manage your pagination keys and secrets
1Password keeps your API keys and environment secrets organized, ensuring your pagination logic remains secure and consistent across environments.
Manage your API secrets with 1Password →Choosing the right pagination strategy is a trade-off between simplicity, performance, and consistency. In this guide, we explore the four most common patterns used by world-class APIs like GitHub, Stripe, and Twitter.
📡 Monitor your APIs — know when they go down before your users do
Better Stack checks uptime every 30 seconds with instant Slack, email & SMS alerts. Free tier available.
Affiliate link — we may earn a commission at no extra cost to you
1. Offset Pagination
The most common and simplest form of pagination. It uses two parameters: limit (how many items per page) and offset (how many items to skip).
GET /api/users?limit=20&offset=40
Pros: Easy to implement, allows jumping to a specific page.
Cons: Performance degrades as the offset increases (database must scan all previous rows), and it's prone to "drifting" if items are added/removed during pagination.
2. Cursor-Based Pagination
Instead of an offset, the API provides a "cursor"—an opaque string that identifies the last item on the current page. The client sends this cursor back to fetch the next page.
GET /api/users?limit=20&cursor=Ym9va21hcms1Mjg5
Pros: Constant performance regardless of page size, no drifting (items don't skip or repeat), the gold standard for high-scale production APIs.
Cons: Cannot jump to a specific page; clients must iterate through the pages sequentially.
Monitor API Performance at Scale
Better Stack provides the visibility you need to ensure your paginated endpoints remain fast as your data grows.
Try Better Stack Free →📡 Monitor your API response times as data grows
Better Stack helps you monitor the performance of your paginated endpoints, alerting you when latency increases as your dataset grows.
Optimise your API performance with Better Stack →3. Keyset Pagination
Similar to cursor pagination, but the cursor is a visible value from the sorted column (e.g., a timestamp or an ID).
GET /api/users?limit=20&since_id=10250
Pros: Efficient and stable. Great for "infinite scroll" feeds.
Cons: Requires the sorting column to be indexed and unique.
4. Page Number Pagination
A simplified version of offset pagination where the API calculates the offset internally based on the page number.
GET /api/users?page=3
Pros: Most intuitive for human-readable URLs.
Cons: Same performance and drifting issues as offset pagination.
Implementation Checklist: The Production Way
- Always specify a maximum limit: Prevent clients from requesting 1 million rows in one go and crashing your server.
- Include a
next_cursororhas_moreflag: Tell the client clearly if there more data to fetch. - Use consistent sorting: Without a consistent sort order, your pagination will be erratic.
- Consistent response headers: Provide total count if possible, or just the laest cursor.
Build a high-performance API
Whether you use cursors or offsets, your API's performance is monitoring. Start monitoring your endpoints in real-time to ensure a steady user experience.
Visit API Status Check →Related guides:
🛠 Tools We Use & Recommend
Tested across our own infrastructure monitoring 200+ APIs daily
Uptime Monitoring & Incident Management
Used by 100,000+ websites
Monitors your APIs every 30 seconds. Instant alerts via Slack, email, SMS, and phone calls when something goes down.
“We use Better Stack to monitor every API on this site. It caught 23 outages last month before users reported them.”
Secrets Management & Developer Security
Trusted by 150,000+ businesses
Manage API keys, database passwords, and service tokens with CLI integration and automatic rotation.
“After covering dozens of outages caused by leaked credentials, we recommend every team use a secrets manager.”
Automated Personal Data Removal
Removes data from 350+ brokers
Removes your personal data from 350+ data broker sites. Protects against phishing and social engineering attacks.
“Service outages sometimes involve data breaches. Optery keeps your personal info off the sites attackers use first.”
AI Voice & Audio Generation
Used by 1M+ developers
Text-to-speech, voice cloning, and audio AI for developers. Build voice features into your apps with a simple API.
“The best AI voice API we've tested — natural-sounding speech with low latency. Essential for any app adding voice features.”
SEO & Site Performance Monitoring
Used by 10M+ marketers
Track your site health, uptime, search rankings, and competitor movements from one dashboard.
“We use SEMrush to track how our API status pages rank and catch site health issues early.”