Why Contentful is moving to cursor-based pagination across all content APIs

Pagination is one of those API design choices that feels simple. Simple, that is, until scale, data volatility, and performance expectations start to collide. As content repositories grow into the millions and teams update content continuously, the way APIs paginate results becomes a critical factor in reliability and developer trust.

At Contentful, we’ve introduced cursor-based pagination across all content APIs to better support large, dynamic datasets. This change reflects how modern APIs are evolving and what’s required to deliver predictable performance as customer environments scale.

In this article, we’ll explain how cursor-based pagination works, why offset-based pagination breaks down at scale, and what this shift means for developers building on Contentful.

Pagination explained with a simple metaphor

Pagination is how APIs return large result sets in manageable chunks instead of delivering everything in a single response. Two approaches dominate API design today: offset-based pagination and cursor-based pagination.

One way to understand the difference is to imagine reading a physical book. Offset-based pagination is like flipping directly to page 50. You can jump to any page number you want, but if someone inserts or removes pages earlier in the book, page 50 no longer contains what you expected.

Cursor-based pagination is more like placing a bookmark at the last paragraph you read. When you return, you continue from a precise position, regardless of what changed earlier in the book.

Both approaches have valid use cases, but they behave very differently once datasets become large and content changes frequently.

Offset-based pagination: Where it works and where it struggles

Offset-based pagination has long been a default choice for APIs. It’s simple to understand and easy to implement: clients pass an offset and a limit, often mirroring familiar SQL patterns such as LIMIT and OFFSET. For relatively static datasets, this model works well and allows developers to jump directly to a specific page of results.

As datasets grow and content becomes more dynamic, however, several limitations emerge.

One challenge is data drift. If content is added, removed, or reordered between paginated requests, offset-based pagination can return duplicate items or skip others entirely. In collaborative or near–real-time content environments, this behavior is difficult to reason about and hard to debug.

Another issue is total result counting. Offset-based pagination often relies on knowing how many total results exist in order to calculate page numbers and metadata. In practice, counting large numbers of rows in a database is an expensive operation. As datasets scale, this count must be computed repeatedly, slowing down paginated requests and consuming database resources that could otherwise serve user-facing workloads.

Performance also degrades as offsets grow larger. Deep pagination forces the database to scan and discard many rows before returning results, which becomes increasingly inefficient at scale.

Taken together, these characteristics make offset-based pagination a poor fit for environments where content changes frequently and predictable performance is a requirement.

Example request (offset-based pagination)

Copy to clipboard

Example response (offset-based pagination)

Copy to clipboard

Cursor-based pagination: Designed for dynamic data

Cursor-based pagination approaches the problem from a different angle. Instead of requesting a numbered page, clients ask for the next set of results after a specific item. Each response includes a cursor that points to the last item returned, and subsequent requests resume from that exact position.

This model provides a more stable way to traverse changing datasets. Because each page builds directly on the previous one, items are far less likely to be skipped or duplicated when content is added or removed between requests.

Cursor-based pagination also avoids deep dataset scans. Rather than skipping over large numbers of rows, the database continues from a known position. In Contentful’s implementation, this is paired with a deliberate design choice to remove total result counting entirely, eliminating one of the most expensive operations involved in paginated queries.

There are trade-offs. Cursor-based pagination is more complex to implement and reason about than numeric offsets. Cursors are opaque, and arbitrary jumps—such as navigating directly to a specific page number—aren’t supported.

In Contentful’s case, this complexity is amplified by the flexibility of our querying model. Supporting arbitrary filters, custom sorting, and locale-specific fields while maintaining stable, deterministic cursors required careful design. Because total counts are intentionally omitted, the total number of pages isn’t known upfront; only the final page indicates that it’s the last.

These trade-offs are intentional and reflect a shift in priorities toward consistency, reliability, and scalability.

Example request (cursor-based pagination)

Copy to clipboard

Example response (cursor-based pagination)

Copy to clipboard

Why Contentful is making this change

Contentful environments are inherently dynamic. Entries are created, updated, localized, and deleted continuously, often by multiple teams working in parallel. At the same time, many customers manage very large content repositories, sometimes consisting of millions of entries across multiple spaces and locales.

In this context, predictable API behavior matters more than the ability to jump to an arbitrary page number. Cursor-based pagination aligns with these requirements by supporting consistent traversal through changing datasets, reducing database load, and scaling more effectively as content volumes grow.

This approach also aligns with established best practices in GraphQL and modern REST API design, where cursor-based pagination has become the preferred model for large, dynamic datasets.

What this means for developers and customers

For developers building on Contentful, cursor-based pagination delivers more predictable API behavior in environments where content changes frequently. Issues related to duplicate or missing entries during pagination are significantly reduced, particularly in integration workflows and automation scenarios.

Performance becomes more consistent as well. By removing total counts and avoiding deep pagination scans, APIs can serve content efficiently regardless of how large a result set becomes. This is especially important for customers operating at scale, where pagination performance directly affects reliability across downstream systems.

Adopting cursor-based pagination across Contentful’s APIs also creates a more consistent developer experience. Whether you’re working with REST or GraphQL, pagination follows the same conceptual model and aligns with modern expectations for API-first architectures.

Next steps

Cursor-based pagination is now supported across all major Contentful content APIs. Developers migrating from offset-based pagination should review the updated documentation and migration guides for the Content Management API, Content Delivery API and Content Preview API to understand how to adapt existing integrations.

If you’re designing new integrations, cursor-based pagination provides a more robust foundation for working with large, evolving content datasets and reflects how Contentful is building for the future.

Take a tour

Chat with our team

Your experiences should wow, not wait. Let's talk.