Skip to main content

Pagination

DialStack uses URL-based pagination for all list endpoints, providing efficient and consistent pagination across the API.

Overview​

URL-based pagination uses opaque page tokens embedded in URLs to navigate through large datasets. This approach:

  • Simplifies client code (no need to extract IDs or manage cursors)
  • Performs better at scale (no need to scan and skip records)
  • Handles real-time data correctly (new items don't shift pages)
  • Provides stable results (consistent ordering)

List Response Format​

All list endpoints return a consistent response structure:

{
  "object": "list",
  "url": "/v1/accounts",
  "next_page_url": "/v1/accounts?page=abc123",
  "previous_page_url": null,
  "data": [...]
}
FieldTypeDescription
objectstringAlways "list"
urlstringThe API endpoint for this list
next_page_urlstring | nullURL to fetch the next page, or null if no more items
previous_page_urlstring | nullURL to fetch the previous page, or null if on first page
dataarrayThe actual list of items

Pagination Parameters​

limit​

Controls the number of items to return (default: 10, max: 100).

curl https://api.dialstack.ai/v1/call-logs?limit=50
note

The pagination system uses opaque page tokens embedded in URLs. Always use the complete URLs provided in next_page_url and previous_page_url from the API response. Do not construct URLs manually.

Pagination Example​

Here's a complete example of paginating through call logs:

const DialStack = require('@dialstack/sdk');
const dialstack = new DialStack('your-api-key');

async function listAllCallLogs() {
  const allCallLogs = [];
  let nextPageUrl = null;

  // Fetch first page
  let response = await dialstack.callLogs.list({ limit: 100 });
  allCallLogs.push(...response.data);
  nextPageUrl = response.next_page_url;

  // Fetch remaining pages
  while (nextPageUrl) {
    // The SDK accepts the full URL and extracts the path
    response = await dialstack.request('GET', nextPageUrl);
    allCallLogs.push(...response.data);
    nextPageUrl = response.next_page_url;
  }

  return allCallLogs;
}

Auto-Pagination with SDK​

The DialStack SDK provides automatic pagination using async iterators:

// Automatically iterate through all pages
for await (const callLog of dialstack.callLogs.list().autoPagingEach()) {
  console.log(callLog.id);
}

// Or collect all items into an array
const allCallLogs = await dialstack.callLogs.list().autoPagingToArray({
  limit: 1000, // Maximum items to collect
});

The SDK handles all pagination automatically:

  • Follows next_page_url from each response
  • Stops when no more pages are available
  • Handles errors and retries

Backward Pagination​

To paginate backward (e.g., for a "Previous Page" button):

// Get the first page
const page1 = await dialstack.callLogs.list({ limit: 20 });

// Later, when user clicks "Next"
const page2 = await dialstack.request('GET', page1.next_page_url);

// When user clicks "Previous" from page 2
const backToPage1 = await dialstack.request('GET', page2.previous_page_url);

// Results are returned in the correct order (newest first)

Using with Web Components​

Our web components and React components handle pagination automatically. You don't need to manage page tokens or URLs manually:

<!-- Web Component - pagination handled internally -->
<dialstack-call-logs></dialstack-call-logs>
{
  /* React Component - pagination handled internally */
}
<CallLogs />;

The components automatically:

  • Load the initial page
  • Fetch more items when scrolling or clicking "Load More"
  • Handle page URLs internally
  • Show loading indicators during pagination
  • Support both forward and backward navigation

Ordering​

All list endpoints return items in descending order by creation time (newest first). This ordering is stable and efficient for pagination.

For endpoints with custom sorting (like call logs sorted by start time), the ordering is clearly documented in the API reference.

Best Practices​

✅ DO​

  • Use reasonable page sizes (10-100 items)
  • Follow the URLs from next_page_url and previous_page_url
  • Check next_page_url for null before requesting the next page
  • Use web components or SDK auto-pagination for automatic handling

❌ DON'T​

  • Don't try to construct page tokens yourself (they're opaque)
  • Don't manually build URLs with page parameters
  • Don't exceed the maximum limit of 100 items
  • Don't rely on page token format (it may change)
  • Don't store page URLs long-term (they may expire)