Skip to main content

Pagination

Learn how to navigate through paginated API responses efficiently.

Overview​

Debitura APIs use cursor-based pagination for list endpoints to ensure consistent and performant data retrieval. This guide explains how pagination works and how to implement it in your integration.

Pagination Model​

All list endpoints that return multiple resources use cursor-based pagination. This approach provides:

  • Consistent results - No duplicate or missing items when data changes
  • Performance - Efficient queries regardless of page depth
  • Scalability - Works well with large datasets

Request Parameters​

When calling a list endpoint, you can control pagination using these query parameters:

limit​

  • Type: Integer
  • Default: 20
  • Maximum: 100
  • Description: Number of items to return per page

cursor​

  • Type: String
  • Default: null (first page)
  • Description: Cursor token from previous response to fetch next page

Example Request​

GET /api/v1/cases?limit=50&cursor=abc123xyz

Response Format​

Paginated responses include both the requested data and pagination metadata:

{
  "data": [
    {
      "id": "case_123",
      "status": "active"
      // ... other fields
    },
    // ... more items
  ],
  "pagination": {
    "has_more": true,
    "next_cursor": "xyz789abc",
    "total_count": 247
  }
}

Pagination Metadata​

  • has_more - Boolean indicating if more results are available
  • next_cursor - Cursor token to fetch the next page (null if no more results)
  • total_count - Total number of items matching the query (optional, not all endpoints provide this)

Iterating Through Pages​

To retrieve all results, continue making requests with the next_cursor until has_more is false:

// Example pagination logic will be documented here
async function fetchAllCases() {
  let allCases = [];
  let cursor = null;

  do {
    // Make request with cursor
    const response = await fetchCases({ cursor, limit: 100 });
    allCases.push(...response.data);
    cursor = response.pagination.next_cursor;
  } while (cursor !== null);

  return allCases;
}

Best Practices​

Optimal Page Size​

  • Use larger page sizes (up to 100) to minimize API calls
  • Balance between response size and number of requests
  • Consider your use case (real-time UI vs batch processing)

Cursor Storage​

  • Don't construct cursor values manually - always use values from API responses
  • Cursors may expire after some time - handle invalid cursor errors gracefully
  • Don't persist cursors long-term - they're meant for immediate pagination

Performance Considerations​

  • Fetch only the page size you need to minimize data transfer
  • Implement client-side caching to avoid redundant requests
  • Use pagination for all list operations, even if you expect few results

Error Handling​

Handle these pagination-specific errors:

  • invalid_cursor - Cursor expired or invalid, restart from first page
  • invalid_limit - Limit parameter outside acceptable range

Filtering and Sorting with Pagination​

When combining pagination with filtering and sorting:

  • Apply filters and sort parameters to all paginated requests
  • Keep filters consistent across all pages of the same query
  • See Filtering and Sorting for details

Examples​

Fetching First Page​

GET /api/v1/cases?limit=20

Fetching Next Page​

GET /api/v1/cases?limit=20&cursor=eyJpZCI6MTIzNH0

With Filters​

GET /api/v1/cases?limit=50&status=active&cursor=eyJpZCI6MTIzNH0