Skip to main content

Pagination

Learn how to efficiently handle large result sets using pagination in the Audian API.

Overview​

When requesting lists of resources, results are paginated to ensure optimal performance. The API returns a limited number of items per page and provides information to access other pages.

Default Pagination​

By default, list endpoints return 25 items per page:

GET https://api.audian.com:8443/v2/accounts/{ACCOUNT_ID}/users

Returns:

{
  "auth_token": "{AUTH_TOKEN}",
  "data": [ /* up to 25 items */ ],
  "page_size": 25,
  "start_key": "user_xyz789",
  "request_id": "{REQUEST_ID}",
  "status": "success"
}

Pagination Parameters​

Page Size Parameter​

Control items per page (max 100):

# Get 10 items per page
GET /accounts/{ACCOUNT_ID}/users?page_size=10

# Get 50 items per page
GET /accounts/{ACCOUNT_ID}/users?page_size=50

# Default is 25
GET /accounts/{ACCOUNT_ID}/users

Start Key Parameter​

Navigate to next page using the start_key from the previous response:

# First page
GET /accounts/{ACCOUNT_ID}/users?page_size=25

# Response includes start_key: "user_xyz789"

# Next page
GET /accounts/{ACCOUNT_ID}/users?page_size=25&start_key=user_xyz789

Pagination Metadata​

Every list response includes pagination info:

{
  "data": [ /* items */ ],
  "page_size": 25,
  "start_key": "user_xyz789",
  "next_start_key": "user_abc123"
}

Understanding Metadata​

  • page_size: Number of items returned per request
  • start_key: Key of the first item in current page
  • next_start_key: Key to use for fetching the next page (if more pages exist)

When next_start_key is not present or is empty, you've reached the last page.

Code Examples​

Python - Get All Pages​

import requests

API_KEY = 'your_api_key'
ACCOUNT_ID = 'your_account_id'
url = f'https://api.audian.com:8443/v2/accounts/{ACCOUNT_ID}/users'
headers = {'X-Auth-Token': API_KEY}

all_items = []
page_size = 25
start_key = None

while True:
    params = {'page_size': page_size}
    if start_key:
        params['start_key'] = start_key

    response = requests.get(url, headers=headers, params=params)
    data = response.json()

    if data['status'] != 'success':
        break

    all_items.extend(data['data'])

    # Check if more pages exist
    next_key = data.get('next_start_key')
    if not next_key:
        break

    start_key = next_key

print(f"Retrieved {len(all_items)} users total")

Node.js - Pagination Loop​

const API_KEY = 'your_api_key';
const ACCOUNT_ID = 'your_account_id';

async function getAllUsers() {
  const url = `https://api.audian.com:8443/v2/accounts/${ACCOUNT_ID}/users`;
  const headers = { 'X-Auth-Token': API_KEY };

  let allItems = [];
  let startKey = null;
  const pageSize = 25;

  while (true) {
    const params = new URLSearchParams({ page_size: pageSize });
    if (startKey) {
      params.append('start_key', startKey);
    }

    const response = await fetch(`${url}?${params}`, { headers });
    const data = await response.json();

    allItems = allItems.concat(data.data);

    if (!data.next_start_key) break;

    startKey = data.next_start_key;
  }

  return allItems;
}

getAllUsers().then(items => {
  console.log(`Retrieved ${items.length} users`);
});

Filtering with Pagination​

Combine filtering and pagination:

# Get first 25 enabled users
GET /accounts/{ACCOUNT_ID}/users?filter_status=enabled&page_size=25

# Get next page of enabled users
GET /accounts/{ACCOUNT_ID}/users?filter_status=enabled&page_size=25&start_key=user_xyz789

CDR Pagination​

Call Detail Records use date-based pagination:

# Get CDRs with date range
GET /accounts/{ACCOUNT_ID}/cdrs?created_from=63876672000&created_to=63876758400&page_size=50

# Next page
GET /accounts/{ACCOUNT_ID}/cdrs?created_from=63876672000&created_to=63876758400&page_size=50&start_key=cdr_abc123

Best Practices​

Do's ✓​

  • Always check for next_start_key before fetching next page
  • Use reasonable page sizes (25-50)
  • Cache results if re-accessed
  • Implement timeouts for large exports
  • Use filtering to reduce dataset size
  • Store start_key for reliable pagination

Don'ts ✗​

  • Don't use page_size > 100
  • Don't assume data won't change between requests
  • Don't make unlimited requests
  • Don't ignore pagination metadata

Performance Tips​

1. Batch Processing​

def process_all_users_in_batches():
    page_size = 50
    start_key = None

    while True:
        params = {'page_size': page_size}
        if start_key:
            params['start_key'] = start_key

        response = requests.get(
            f'https://api.audian.com:8443/v2/accounts/{ACCOUNT_ID}/users',
            headers={'X-Auth-Token': API_KEY},
            params=params
        )

        data = response.json()
        items = data['data']

        # Process batch
        process_batch(items)

        # Check for more
        if not data.get('next_start_key'):
            break

        start_key = data['next_start_key']

Troubleshooting​

"Invalid page_size"​

{
  "data": {
    "message": "page_size must be between 1 and 100"
  },
  "error": "400"
}

Solutions:

  • Set page_size between 1 and 100
  • Use default of 25 if unsure

No Results on Later Pages​

Solution: Data may have changed between requests. For consistent pagination, use the same filter parameters throughout.

Next Steps​