Pagination for AI Agents: Why Cursor-Based Beats Offset-Based Every Time
When an AI agent iterates through your product catalog, order history, or customer list, it needs every record, in order, with zero duplicates. Offset-based pagination cannot guarantee that. Cursor-based pagination can. Of 500 businesses scanned by AgentHermes, 88% have no pagination support at all on their list endpoints.
The Problem: Agents Cannot Browse — They Iterate
A human browsing a product catalog clicks “Next Page” and scans visually. If an item appears twice or one is missing, they barely notice. An AI agent is different. When an agent pages through your inventory to find the cheapest widget, recommend a product, or reconcile an order list, it processes every single record programmatically. A duplicate means the agent counts it twice. A missing item means the agent makes a recommendation without seeing the best option.
This is not a theoretical concern. Any API that accepts writes while an agent reads will mutate data between pagination requests. A new product added to page 2 shifts everything after it — the agent sees item #40 twice on page 2 and page 3, and never sees item #41 at all. The agent does not know this happened. There is no error. The data just silently corrupts.
AgentHermes scans specifically for pagination patterns in D9 Agent Experience because this is one of the most common silent failures in agent-API interactions.
The Three Pagination Patterns Agents Encounter
Every paginated API falls into one of three patterns. Only two of them are safe for autonomous agents.
Offset-Based
Not agent-safeThe classic page=2&limit=20 pattern. The server skips rows to find the starting point. Works when data is static, breaks when data changes between requests.
Example: GET /products?page=3&limit=20 → skips 40, returns 41-60
The failure mode: If a new product is inserted while the agent pages through, it either sees duplicates or misses items entirely. The agent has no way to detect this.
Cursor-Based
Agent-safeEach response includes a cursor token pointing to the last item. The next request uses after=cursor to get the next batch. Position is anchored to a specific record, not an offset.
Example: GET /products?limit=20&after=prod_abc123 → returns 20 items after that ID
Why it works: None for agents. Stable across inserts, deletes, and concurrent modifications. The agent always gets a consistent, complete view of the data.
Keyset-Based
Agent-safeA variant of cursor pagination using a natural sort key (timestamp, ID) instead of an opaque token. Requires a stable, unique sort column. Fastest at scale because the database uses an index seek instead of a skip.
Example: GET /orders?created_after=2026-04-15T00:00:00Z&limit=50
Why it works: Minor: requires the sort key to be exposed in the API. Some APIs hide internal IDs. But for agents, this transparency is a feature, not a bug.
Offset vs Cursor: Head-to-Head
Every dimension where agents care about data integrity, cursor-based pagination wins.
Real-World Examples: Who Gets It Right
The top-scoring APIs in our 500-business scan all implement cursor-based pagination. The pattern is consistent — companies that build for developers build for agents.
Stripe
Score: 68Cursor-based with has_more + starting_after. Every list endpoint supports it. Auto-pagination in SDKs.
Gold standard
GitHub
Score: 67Both offset (page=N) and cursor (after=Y2FwdG...) via GraphQL. REST uses Link headers with rel="next". Cursor wins on the GraphQL API.
Dual support — cursor recommended
Shopify
Score: 52GraphQL cursor-based by default. REST uses page_info cursor tokens since 2019, phasing out page-based. Good migration story.
Cursor by default
Most APIs (88%)
No pagination at all. Return all results in one response (if under 100) or truncate silently. Agent gets partial data and does not know it.
Invisible data loss
The pattern is clear: APIs built for programmatic consumption — Stripe, GitHub, Shopify — default to cursor-based pagination. APIs built for human dashboards — most SaaS admin panels, e-commerce backends, local business tools — either have no pagination or use offset-only. The former are agent-ready. The latter silently lose data when agents use them.
What AgentHermes Checks in D9
Pagination is one of seven signals in D9 Agent Experience (10% weight). Here is exactly what gets checked.
Cursor parameters in API
Response includes after, before, cursor, starting_after, or ending_before parameters.
has_more or next indicator
Response body includes has_more: true/false, next_cursor, or next_page_token so the agent knows when to stop.
Consistent across endpoints
All list endpoints use the same pagination pattern. Mixing offset on /products and cursor on /orders confuses agents.
Link headers (REST)
For REST APIs, Link: <url>; rel="next" headers provide the next page URL. Agents follow these without parsing response bodies.
Pagination alone does not make or break a score. But combined with the other D9 signals — request IDs, structured errors, response envelopes, rate-limit headers, idempotency keys, and OpenAPI examples — it separates APIs that agents can use reliably from APIs that produce silent data corruption.
The Minimum Viable Agent-Safe Pagination
You do not need to rewrite your API. The minimum cursor-based pagination adds three things to any list endpoint response.
Response envelope with cursor pagination:
{
"data": [...],
"has_more": true,
"next_cursor": "prod_abc123",
"total_count": 1847
}data contains the current page of results. has_more tells the agent whether to continue. next_cursor is the opaque token for the next request. total_count is optional but helpful — it lets the agent estimate progress and set expectations for the user.
The agent’s loop becomes trivial: fetch, process, check has_more, pass next_cursor, repeat. No page math. No offset arithmetic. No silent data loss. If the connection drops, the agent resumes from the last cursor. This is what agent-safe pagination looks like.
Migration tip: If you currently use offset-based pagination, add cursor support alongside it. Accept both page=2&limit=20 and after=prod_abc123&limit=20 on the same endpoint. Document cursor as the recommended approach. Remove offset support in your next major version.
Frequently Asked Questions
Why do agents paginate differently than humans?
Humans browse one page at a time and tolerate duplicates or missing items. Agents iterate through entire datasets programmatically to build complete context. A missed item or duplicate can cascade into wrong decisions — recommending an out-of-stock product, double-booking an appointment, or producing an incomplete report. Agents need pagination that guarantees completeness.
Can I support both offset and cursor pagination?
Yes, and you should during migration. Stripe and GitHub both offer dual support. The key is making cursor the default and documenting it as the recommended pattern. AgentHermes D9 checks specifically for cursor support — offset-only will not earn full D9 points even if it works.
What does AgentHermes check for pagination?
D9 Agent Experience includes pagination as a scored signal. We check for: cursor or after/before parameters in API responses, has_more or next_cursor fields in response bodies, Link headers with rel="next" for REST APIs, and consistent pagination across all list endpoints. Missing pagination on list endpoints that return more than 20 items is a D9 penalty.
How does pagination affect the Agent Readiness Score?
Pagination is part of D9 Agent Experience (10% weight) and D2 API Quality (15% weight). An API with proper cursor pagination earns points in both dimensions. An API with no pagination or offset-only pagination loses points in D9 specifically. The combined impact is typically 2-4 points on the overall score — enough to push a Bronze business into Silver.
Does your API paginate safely for agents?
Run a free Agent Readiness Scan to see your D9 Agent Experience score, including pagination support, across all 9 dimensions.