Pagination

When working with list endpoints that return large result sets, the Airclou API uses cursor-based pagination to help you retrieve data efficiently.

How it works

List endpoints return a maximum of 100 items per request by default. If there are more results available, the response includes a next_cursor value that you can use to fetch the next page.

curl "https://app.airclou.com/playbook/api/v1/users?limit=50" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "data": [
    {
      "id": "usr_001",
      "email": "user1@example.com",
      "name": "User One"
    },
    // ... 49 more users
  ],
  "pagination": {
    "next_cursor": "eyJpZCI6InVzcl8wNTAiLCJ0cyI6MTczNTgyNDAwMH0",
    "has_more": true,
    "total_count": 250
  }
}

Fetching the next page

To retrieve the next page, include the cursor parameter with the value from next_cursor:

curl "https://app.airclou.com/playbook/api/v1/users?limit=50&cursor=eyJpZCI6InVzcl8wNTAiLCJ0cyI6MTczNTgyNDAwMH0" \
  -H "Authorization: Bearer YOUR_API_KEY"

Continue making requests with the updated cursor until has_more is false.

Parameters

All list endpoints support these pagination parameters:

Parameter	Type	Description	Default
limit	integer	Number of items to return (1-100)	50
cursor	string	Cursor for pagination	—

Best practices

Use appropriate page sizes

Choose a page size that balances performance and memory usage:

• Small pages (10-25) — Better for real-time UI updates
• Medium pages (50-75) — Good balance for most use cases
• Large pages (100) — Best for batch processing

Handle rate limits

When paginating through large datasets, be mindful of rate limits:

async function fetchAllUsers() {
  const users = [];
  let cursor = null;
  
  do {
    const response = await fetch(
      `https://app.airclou.com/playbook/api/v1/users?limit=100${cursor ? `&cursor=${cursor}` : ''}`,
      {
        headers: { 'Authorization': `Bearer ${apiKey}` }
      }
    );
    
    const data = await response.json();
    users.push(...data.data);
    cursor = data.pagination.next_cursor;
    
    // Respect rate limits
    if (data.pagination.has_more) {
      await new Promise(resolve => setTimeout(resolve, 100));
    }
  } while (cursor);
  
  return users;
}

Store cursors temporarily

Cursors are valid for 24 hours. If you need to resume pagination later, store the cursor value. After 24 hours, you’ll need to start from the beginning.

Filtering and sorting

Pagination works seamlessly with filtering and sorting parameters:

curl "https://app.airclou.com/playbook/api/v1/users?role=admin&sort=created_at&order=desc&limit=25" \
  -H "Authorization: Bearer YOUR_API_KEY"

The cursor automatically maintains your filter and sort preferences across pages.

Total count

The total_count field in the pagination object provides the total number of items matching your query. This is useful for:

• Displaying “Page X of Y” indicators
• Calculating progress bars
• Determining if pagination is needed

Note that for performance reasons, total_count is capped at 10,000 for very large result sets.

Edge cases

Empty results

If there are no results, the response includes an empty data array:

{
  "data": [],
  "pagination": {
    "next_cursor": null,
    "has_more": false,
    "total_count": 0
  }
}

Invalid cursor

If you provide an invalid or expired cursor, you’ll receive a 400 Bad Request error:

{
  "error": {
    "code": "invalid_cursor",
    "message": "The provided cursor is invalid or expired"
  }
}

In this case, restart pagination from the beginning without a cursor parameter.