How to Paginate CloudTalk API Collection Responses

Most core API list endpoints — call history, contacts, agents, tags and the rest — return resources in pages rather than all at once. You control page size with the limit parameter and navigate between pages with the page parameter. Their responses include four metadata fields that tell you how many total records match your query and how many pages remain, giving you what you need to walk through a large result set without guesswork.

Pagination is per-endpoint, not universal. List countries, for example, returns a plain array inside responseData and accepts no page or limit. Check whether the endpoint documents these parameters before building a paging loop around it.

Dialer endpoints paginate differently. They are cursor-based: pass limit (1–100, default 50) plus an opaque cursor, and read the next cursor from meta.nextCursor in the response. A null nextCursor means there are no more pages. The page, pageCount and itemsCount fields described below do not apply there.

Query Parameters

Append these parameters to any collection endpoint URL to control pagination behavior.

integer

Number of items to return per page. Must be between 1 and 1000. Omit it and the server applies its own default, which it reports back in the envelope’s limit field. Use larger values (100–500) for batch export jobs and smaller values when you only need the most recent records.

integer

Page number to retrieve, starting at 1. Omit it to get the first page.

Response Envelope Fields

Paginated core API list endpoints wrap their payload in the standard responseData envelope. The following fields drive your iteration logic.

integer int64

required

Total number of resources matching your query across all pages. Use this to show record counts in your UI or to estimate job duration.

integer int64

required

Total number of pages available for the current limit. When pageNumber equals pageCount, you have reached the last page.

integer int64

required

The page number included in this response (1-indexed). Mirrors the page query parameter you sent.

integer int64

required

The maximum number of items per page as applied by the server. Mirrors the limit query parameter you sent, or the server default if you omitted it.

array

required

The resource objects for the current page. An empty array ([]) means no results matched your query.

Iterating Through Pages

The simplest iteration strategy is to keep incrementing page until pageNumber equals pageCount. Drive your loop off pageCount rather than off what happens past the last page — that behaviour is not part of the documented contract.

Send your first request

Issue a request with page=1 and your desired limit. Read pageCount from the response to know how many total requests you need.

Process the current page

Iterate over the data array and process each record — write to a database, transform for another API, queue for async work, etc.

Check for more pages

Compare pageNumber to pageCount. If pageNumber < pageCount, increment page by 1 and repeat from Step 1.

Stop when done

When pageNumber === pageCount, you have consumed all matching records. Treat an empty data array as a stop condition too, so a mid-run change in the result set cannot spin the loop.

Examples

curl -u KEY_ID:KEY_SECRET \
  -H "Accept: application/json" \
  'https://my.cloudtalk.io/api/calls/index.json?limit=100&page=1'

curl -u KEY_ID:KEY_SECRET \
  -H "Accept: application/json" \
  'https://my.cloudtalk.io/api/calls/index.json?limit=100&page=2'

The following Python example fetches every page of calls within a date range and collects all records into a single list.

Python — fetch all pages

import requests

BASE_URL = "https://my.cloudtalk.io/api/calls/index.json"
KEY_ID = "your_key_id"
KEY_SECRET = "your_key_secret"

def fetch_all_calls(date_from: str, date_to: str, limit: int = 100) -> list:
    """Fetch every page of calls between date_from and date_to."""
    all_calls = []
    page = 1

    while True:
        params = {
            "limit": limit,
            "page": page,
            "date_from": date_from,
            "date_to": date_to,
        }
        response = requests.get(
            BASE_URL,
            auth=(KEY_ID, KEY_SECRET),
            headers={"Accept": "application/json"},
            params=params,
        )
        response.raise_for_status()

        envelope = response.json()["responseData"]
        all_calls.extend(envelope["data"])

        print(
            f"Fetched page {envelope['pageNumber']} of {envelope['pageCount']} "
            f"({len(envelope['data'])} records)"
        )

        # Stop when we have retrieved the final page
        if envelope["pageNumber"] >= envelope["pageCount"]:
            break

        page += 1

    print(f"Total records retrieved: {len(all_calls)} of {envelope['itemsCount']}")
    return all_calls


calls = fetch_all_calls("2024-01-01 00:00:00", "2024-01-31 23:59:59")

Best Practices

Use a limit between 100 and 500 for background batch jobs. This balances response latency, memory consumption, and the number of round-trips required to export large datasets.

Filter before you paginate. Call history accepts date_from, date_to, contact_id, user_id, type, status, tag_id and call_id; List contacts accepts country_id, tag_id, industry and keyword. Filters differ per endpoint — a tight filter dramatically reduces itemsCount and the number of pages you walk through.
Don’t rely on absolute page offsets for real-time data. If new records are created between page requests, a record may appear on two consecutive pages or be skipped. For near-real-time sync, re-query with a narrow date_from / date_to window on endpoints that support it, rather than resuming from a page number.
Handle empty pages gracefully. If data is an empty array, stop iterating rather than retrying.
Respect rate limits. Tight pagination loops can exhaust your 60 requests-per-minute budget quickly. Add a short sleep between pages or use the largest limit your use case allows. See the Rate Limiting guide for details.

Conversation Intelligence Pagination

Conversation Intelligence is not a paginated collection of calls. There is no endpoint that lists CI calls. Every CI endpoint takes a single call ID — /ai/calls/{callId}/summary, /overall-sentiment, /talk-listen-ratio, /topics, /transcription, /smart-notes, /details-link — and returns data for that one call.

Two of those endpoints paginate, and they paginate within a call: Topics and Transcription. Both use offset/limit rather than the page-based scheme above, and neither uses the responseData envelope.

integer

Maximum number of records to return in a single response. Minimum 1.

integer

default:"0"

Number of records to skip before returning results. To move to the next page, add limit to the previous offset.

The payload sits under a top-level data object, with a sibling pagination object carrying limit, offset and total:

Transcription response (abridged)

{
  "data": {
    "callId": 12345,
    "segments": [
      { "start": 1.501, "end": 4.599, "caller": "caller2", "text": "Hello, I would like to ask for help." },
      { "start": 5.173, "end": 8.599, "caller": "caller1", "text": "Hi. What's your issue?" }
    ],
    "callers": [
      { "id": 5000, "type": "contact", "localIdentifier": "caller1" },
      { "id": 1000, "type": "agent", "localIdentifier": "caller2" }
    ],
    "language": "en"
  },
  "pagination": { "limit": 2, "offset": 0, "total": 10 }
}

To read a full transcription, keep incrementing offset by limit until offset >= pagination.total. The segments accumulate; data.callId, data.callers and data.language repeat on every page.

Python — fetch a complete transcription

import requests

CI_BASE = "https://api.cloudtalk.io/v1"
KEY_ID = "your_key_id"
KEY_SECRET = "your_key_secret"


def fetch_transcription(call_id: int, limit: int = 50) -> list:
    """Fetch every transcription segment for a single call."""
    segments = []
    offset = 0

    while True:
        response = requests.get(
            f"{CI_BASE}/ai/calls/{call_id}/transcription",
            auth=(KEY_ID, KEY_SECRET),
            headers={"Accept": "application/json"},
            params={"limit": limit, "offset": offset},
        )
        response.raise_for_status()
        body = response.json()

        segments.extend(body["data"]["segments"])

        offset += limit
        if offset >= body["pagination"]["total"]:
            break

    return segments


for segment in fetch_transcription(12345):
    print(f"[{segment['start']:.1f}s] {segment['caller']}: {segment['text']}")

To work across many calls, page through Call history on the core API first, then request Conversation Intelligence per call ID from that list.

Getting Started

API Concepts

Changelog

How to Paginate CloudTalk API Collection Responses

Query Parameters

Response Envelope Fields

Iterating Through Pages

Examples

Best Practices

​Query Parameters

​Response Envelope Fields

​Iterating Through Pages

​Examples

​Best Practices

​Conversation Intelligence Pagination

Query Parameters

Response Envelope Fields

Iterating Through Pages

Examples

Best Practices

Conversation Intelligence Pagination