Pagination Patterns: Offset vs Cursor-Based

While I was reviewing some API designs the other day, I came across a situation that I was once guilty of myself—blindly implementing offset pagination for every single endpoint without thinking about the consequences. It wasn't until our social feed started showing duplicate posts during active hours that I realized there was a better way.

Let me share what I discovered about pagination patterns and how choosing the right one can make or break your API's performance and user experience.

Why Pagination Strategy Matters for Your API

When I first started building APIs, pagination seemed straightforward. You add ?page=1&limit=20 to your endpoint and call it a day. Little did I know that this simple decision would come back to haunt me months later when our application started handling real-time data.

The pagination pattern you choose affects three critical aspects: performance at scale, data consistency during traversal, and user experience. I cannot stress this enough! A poor pagination choice can turn a smooth-scrolling feed into a frustrating experience where users see the same items twice or miss content entirely.

Here's the thing—there's no universally "best" pagination pattern. Each approach solves different problems, and understanding when to use which pattern is what separates okay APIs from great ones.

Offset Pagination: How It Works and When to Use It

Offset pagination is what most of us learned first, and for good reason—it's intuitive. You specify how many items to skip (offset) and how many to return (limit). Think of it like turning pages in a book where you can jump directly to page 5.

The database query looks something like this: "Skip the first 40 records and give me the next 20." This maps perfectly to SQL's OFFSET and LIMIT clauses, making it feel natural to implement.

I used offset pagination extensively in my early projects because it allowed users to navigate to any page directly. Need to jump to page 10? No problem. Want to go back to page 3? Easy. This random access capability made it perfect for scenarios like search results or administrative dashboards where users might want to navigate non-sequentially.

However, I discovered its dark side when working on a comment system. During active hours, new comments would push older ones down the list. When a user moved from page 1 to page 2, they'd see some comments twice because new ones had been inserted while they were viewing page 1. Frustrating!

Implementing Offset Pagination in Node.js

Let me show you how I typically implement offset pagination in a TypeScript API. This example uses Express and assumes you have some database client available:

import { Request, Response } from 'express'
 
interface PaginationParams {
  page: number
  limit: number
}
 
interface PaginatedResponse<T> {
  data: T[]
  pagination: {
    currentPage: number
    totalPages: number
    totalItems: number
    itemsPerPage: number
  }
}
 
async function getProducts(req: Request, res: Response) {
  // Parse and validate pagination parameters
  const page = Math.max(1, parseInt(req.query.page as string) || 1)
  const limit = Math.min(100, Math.max(1, parseInt(req.query.limit as string) || 20))
  
  // Calculate offset
  const offset = (page - 1) * limit
  
  try {
    // Fetch data with offset and limit
    const products = await db.query(
      'SELECT * FROM products ORDER BY created_at DESC LIMIT $1 OFFSET $2',
      [limit, offset]
    )
    
    // Get total count for pagination metadata
    const countResult = await db.query('SELECT COUNT(*) FROM products')
    const totalItems = parseInt(countResult.rows[0].count)
    const totalPages = Math.ceil(totalItems / limit)
    
    const response: PaginatedResponse<Product> = {
      data: products.rows,
      pagination: {
        currentPage: page,
        totalPages,
        totalItems,
        itemsPerPage: limit
      }
    }
    
    return res.json(response)
  } catch (error) {
    return res.status(500).json({ error: 'Failed to fetch products' })
  }
}

Notice how I'm clamping the limit value between 1 and 100? I learned this the hard way when someone requested limit=999999 and crashed our database. Always validate and limit your pagination parameters!

The two-query approach (one for data, one for count) is also important. You need that total count to calculate the total number of pages for your UI. In other words, without it, you can't show users "Page 3 of 47" or render proper pagination controls.

Cursor-Based Pagination: The Real-Time Solution

When I finally decided to dig into cursor-based pagination, everything clicked. Instead of using numeric offsets, you use a unique identifier (the cursor) to mark your position in the dataset. Think of it like a bookmark that marks exactly where you left off.

The key insight? Instead of asking for "the next 20 items after skipping 40," you ask for "the next 20 items after this specific item." This approach eliminates the duplicate/missing item problem because you're always moving forward relative to a fixed point, regardless of insertions or deletions happening elsewhere in the dataset.

Cursor pagination shines in real-time feeds—social media timelines, chat messages, activity streams, or any scenario where data changes frequently while users are browsing. I implemented it for a notification system and the improvement in user experience was immediate. No more seeing the same notification twice when pulling down to refresh!

The trade-off? You lose random access. Users can't jump to page 10 directly. They can only move forward (next) or sometimes backward (previous) sequentially. Luckily we can work around this limitation with smart UX design like infinite scrolling or "load more" buttons.

Building Cursor Pagination with TypeScript

Here's how I implement cursor-based pagination in TypeScript. This example uses a timestamp-based cursor for a social feed:

import { Request, Response } from 'express'
 
interface CursorPaginationParams {
  cursor?: string
  limit: number
}
 
interface CursorPaginatedResponse<T> {
  data: T[]
  pagination: {
    nextCursor: string | null
    hasMore: boolean
  }
}
 
interface Post {
  id: string
  content: string
  created_at: Date
  author_id: string
}
 
async function getFeed(req: Request, res: Response) {
  const limit = Math.min(50, Math.max(1, parseInt(req.query.limit as string) || 20))
  const cursor = req.query.cursor as string | undefined
  
  try {
    let query = 'SELECT * FROM posts WHERE author_id IN (SELECT following_id FROM follows WHERE follower_id = $1)'
    const params: any[] = [req.user.id]
    
    // If cursor exists, add it to the WHERE clause
    if (cursor) {
      // Decode cursor (base64 encoded timestamp)
      const decodedCursor = Buffer.from(cursor, 'base64').toString('utf-8')
      query += ' AND created_at < $2'
      params.push(decodedCursor)
    }
    
    // Always fetch one extra item to check if there are more results
    query += ' ORDER BY created_at DESC LIMIT $' + (params.length + 1)
    params.push(limit + 1)
    
    const result = await db.query(query, params)
    const posts: Post[] = result.rows
    
    // Check if there are more results
    const hasMore = posts.length > limit
    
    // Remove the extra item if it exists
    if (hasMore) {
      posts.pop()
    }
    
    // Generate next cursor from the last item's timestamp
    const nextCursor = hasMore && posts.length > 0
      ? Buffer.from(posts[posts.length - 1].created_at.toISOString()).toString('base64')
      : null
    
    const response: CursorPaginatedResponse<Post> = {
      data: posts,
      pagination: {
        nextCursor,
        hasMore
      }
    }
    
    return res.json(response)
  } catch (error) {
    return res.status(500).json({ error: 'Failed to fetch feed' })
  }
}

The clever part here is fetching limit + 1 items. This extra item tells us whether there are more results without requiring a separate count query. If we get 21 items back when asking for 20, we know there's at least one more page.

I also encode the cursor as base64. This hides implementation details from clients and makes it easier to change the cursor format later without breaking existing API consumers. The cursor could be a timestamp, an ID, or even a compound value—clients don't need to know.

Performance Showdown: Offset vs Cursor at Scale

Here's where things get fascinating! I ran some tests comparing these approaches on a dataset with 10 million records, and the results were eye-opening.

For offset pagination, as the offset value increases, performance degrades linearly. Jumping to page 1000 means the database must scan through 20,000 records just to skip them. On my test PostgreSQL database, fetching page 1 took 12ms, but page 5000 took 847ms. That's a 70x slowdown!

Cursor-based pagination maintains consistent performance regardless of position in the dataset. Whether you're fetching the first page or the millionth, the query time stays roughly the same because you're always using an indexed column for filtering. My tests showed 10-15ms response times consistently across all positions.

However, offset pagination has one performance advantage: it only requires one query to get both data and total count. Cursor pagination needs extra logic (like the limit + 1 trick) to determine if more data exists.

For datasets under 10,000 records with infrequent updates, offset pagination performs fine and offers better UX with direct page access. For larger datasets or real-time data, cursor pagination wins hands down.

Choosing the Right Pattern for Your Use Case

After implementing both patterns across dozens of projects, I've developed a simple decision framework that I use:

Choose offset pagination when:

• Users need random access to pages (search results, admin panels)
• Dataset is relatively small (under 10,000 items)
• Data doesn't change frequently during user sessions
• You need to show total page counts in your UI
• Performance of deep pagination isn't a concern

Choose cursor-based pagination when:

• Building real-time feeds (social media, notifications, activity streams)
• Dataset is large (hundreds of thousands or millions of records)
• Data changes frequently during user sessions
• You're implementing infinite scroll or "load more" UX
• Performance consistency across all positions matters

I typically reach for cursor pagination by default now, unless I have a specific reason to need random page access. The consistency and performance benefits usually outweigh the UX limitations, especially since infinite scroll has become the expected interaction pattern for most feeds.

Pagination Best Practices and Common Pitfalls

Let me share some mistakes I've made so you don't have to learn them the hard way.

Always validate and limit pagination parameters. Without limits, a malicious user can request millions of records and crash your server. I cap limits at 100 and validate that offsets/cursors are properly formatted.

Include pagination metadata in responses. Clients need to know if there are more results and how to fetch them. Don't make them guess or perform client-side calculations.

Use database indexes on cursor columns. If you're using created_at as your cursor, make sure it's indexed! I once forgot this and wondered why my "fast" cursor pagination was slower than offset pagination.

Consider bidirectional cursor pagination for better UX. Allowing users to scroll both directions requires tracking both nextCursor and previousCursor, but it creates a smoother experience.

Don't mix sorting with offset pagination on changing datasets. If your "sort by most popular" query can return different results between page requests, you'll have inconsistent pagination. Use cursor-based approaches for dynamic sorting.

And that concludes the end of this post! I hope you found this valuable and look out for more in the future!