API Pagination Skill | Agent Skills

API Pagination

Overview
When to Use
Quick Start
Reference Guides
Best Practices

Overview

Implement scalable pagination strategies for handling large datasets with efficient querying, navigation, and performance optimization.

When to Use

Returning large collections of resources
Implementing search results pagination
Building infinite scroll interfaces
Optimizing large dataset queries
Managing memory in client applications
Improving API response times

Quick Start

Minimal working example:

// Node.js offset/limit implementation
app.get('/api/users', async (req, res) => {
  const page = parseInt(req.query.page) || 1;
  const limit = Math.min(parseInt(req.query.limit) || 20, 100); // Max 100
  const offset = (page - 1) * limit;

  try {
    const [users, total] = await Promise.all([
      User.find()
        .skip(offset)
        .limit(limit)
        .select('id email firstName lastName createdAt'),
      User.countDocuments()
    ]);

    const totalPages = Math.ceil(total / limit);

    res.json({
      data: users,
      pagination: {
        page,
        limit,
        total,
        totalPages,
        hasNext: page < totalPages,
// ... (see reference guides for full implementation)

Reference Guides

Detailed implementations in the references/ directory:

| Guide | Contents | |---|---| | Offset/Limit Pagination | Offset/Limit Pagination | | Cursor-Based Pagination | Cursor-Based Pagination | | Keyset Pagination | Keyset Pagination | | Search Pagination | Search Pagination | | Pagination Response Formats | Pagination Response Formats | | Python Pagination (SQLAlchemy) | Python Pagination (SQLAlchemy) |

Best Practices

✅ DO

Use cursor pagination for large datasets
Set reasonable maximum limits (e.g., 100)
Include total count when feasible
Provide navigation links
Document pagination strategy
Use indexed fields for sorting
Cache pagination results when appropriate
Handle edge cases (empty results)
Implement consistent pagination formats
Use keyset for extremely large datasets

❌ DON'T

Use offset with billions of rows
Allow unlimited page sizes
Count rows for every request
Paginate without sorting
Change sort order mid-pagination
Use deep pagination without cursor
Skip pagination for large datasets
Expose database pagination directly
Mix pagination strategies
Ignore performance implications

Agent Skills: API Pagination

Install this agent skill to your local

Skill Files