Pagination

List operations return results one page at a time. Each page includes the URL of the next page and the previous one, so you move through a list by following those URLs rather than building them yourself.

List response format

Every list operation returns the same envelope:

JSON

{
  "object": "list",
  "url": "/v1/accounts",
  "next_page_url": "/v1/accounts?page=abc123",
  "previous_page_url": null,
  "data": [...]
}

Field	Type	Description
object	string	Always "list"
url	string	The path of this list
next_page_url	string | null	Path of the next page, or null when there are no more
previous_page_url	string | null	Path of the previous page, or null on the first page
data	array	The items on this page

The page URLs are paths relative to https://api.dialstack.ai, and they keep the filters and limit of the original request.

Page size: limit

limit sets how many items a page holds. It defaults to 10. The maximum depends on the operation: it is 100 for most lists, and lower for a few. The API reference lists the maximum for each one.

Bash

curl "https://api.dialstack.ai/v1/calls?limit=50" \
  -H "Authorization: Bearer sk_test_YOUR_SECRET_KEY" \
  -H "DialStack-Account: YOUR_ACCOUNT_ID"

note

Page URLs carry an opaque page token. Always use the next_page_url and previous_page_url the API returns, and don't build or modify page tokens yourself. A malformed token returns 400 with code invalid_pagination; restart from the first page.

Auto-pagination with the Server SDK

In the Server SDK, list methods return the first page when you await them, and also offer two helpers that follow next_page_url for you:

TypeScript

import { DialStack } from '@dialstack/sdk-server';

const dialstack = new DialStack(process.env.DIALSTACK_API_KEY);
const options = { dialstackAccount: accountId };

// First page only
const page = await dialstack.calls.list({ limit: 100 }, options);

// Every call, one at a time, fetching pages as needed
for await (const call of dialstack.calls.list({ limit: 100 }, options).autoPagingEach()) {
  console.log(call.id);
}

// Or collect into an array, stopping after 1,000 items
const calls = await dialstack.calls
  .list({ limit: 100 }, options)
  .autoPagingToArray({ limit: 1000 });

autoPagingToArray stops at 10,000 items when you don't pass a limit.

Following page URLs yourself

Without the SDK, request each next_page_url until it is null:

TypeScript

async function listAllCalls(accountId: string) {
  const headers = {
    Authorization: `Bearer ${process.env.DIALSTACK_API_KEY}`,
    'DialStack-Account': accountId,
  };
  const calls = [];
  let path: string | null = '/v1/calls?limit=100';

  while (path) {
    const res = await fetch(`https://api.dialstack.ai${path}`, { headers });
    const page = await res.json();
    calls.push(...page.data);
    path = page.next_page_url;
  }

  return calls;
}

To go backward, for a Previous button, request previous_page_url the same way.

Embedded components

The embedded components page through their data on their own. You don't handle page URLs when you render call logs or voicemails with them.

Best practices

• Follow next_page_url and previous_page_url, and stop when next_page_url is null.
• Stay within the operation's maximum limit.
• Don't parse page tokens or rely on their format; it may change.
• Don't store page URLs for later; they may expire.