CloudTalk API Rate Limits, Headers, and Throttling

The CloudTalk REST API (v1.7) enforces a rate limit to ensure fair resource allocation and platform stability for all customers. Every API key in your company shares a single quota, so high-volume background jobs and real-time user-facing calls compete for the same budget. Understanding the limit, reading the headers the API returns, and implementing graceful backoff logic will prevent your integration from hitting 429 errors in production.

Default Limit

CloudTalk enforces a limit of 60 requests per minute per company on the core API. This quota is shared across all API keys in your account — if you have multiple services or background workers issuing API calls, their requests all count toward the same 60 req/min ceiling.

The Dialer partner API has its own budget. Requests to https://api.cloudtalk.io/v1/dialer/* are limited per company in a dedicated 60 req/min budget, so they do not consume the core 60 req/min quota. Dialer 429 responses do carry the same three X-CloudTalkAPI-* headers described below, but the body follows the Dialer error shape: { "statusCode": 429, "message": "Too Many Requests", "error": "Too Many Requests", "correlationId": "YevPQs" }.

When you exceed the rate limit, the API immediately returns HTTP 429 Too Many Requests. On the core API the body follows the standard error envelope — {"responseData": {"status": 429, "message": "Too Many Requests"}}. The request is not queued or retried automatically; you must handle the retry yourself, and continued hammering will not make the window reset any sooner.

Rate-Limit Headers

When a request is rate limited, the API returns a 429 along with three headers describing your quota. Read them from the 429 response to decide when to resume:

Header	Type	Description
`X-CloudTalkAPI-Limit`	integer	Maximum number of requests allowed in the current one-minute window.
`X-CloudTalkAPI-Remaining`	integer	Number of requests you may still make before the window resets.
`X-CloudTalkAPI-ResetTime`	integer (Unix timestamp)	The Unix epoch second at which the current window expires and your quota refills.

Reading Headers with cURL

Use -D - to dump the response headers to stdout, and -o /dev/null to discard the body. Avoid -I: it issues a HEAD request rather than the documented GET.

cURL — inspect response headers

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

When the request is rate limited, the response looks like this:

Sample 429 response headers

HTTP/2 429
content-type: application/json; charset=utf-8
x-cloudtalkapi-limit: 60
x-cloudtalkapi-remaining: 0
x-cloudtalkapi-resettime: 1712150460

Convert X-CloudTalkAPI-ResetTime from Unix timestamp to a human-readable time with date -r 1712150460 (macOS) or date -d @1712150460 (Linux).

These headers are documented as accompanying a 429. If your client observes them on successful responses too, you can use them to track consumption proactively — but do not build logic that requires them to be present outside a 429.

Implementing Retry Logic

The recommended strategy for handling 429 responses is exponential backoff with jitter. Wait for a short delay after the first failure, double the delay on each subsequent failure, and add a small random jitter to prevent multiple workers from retrying in lockstep.

Python — exponential backoff on 429

import time
import random
import requests

KEY_ID = "your_key_id"
KEY_SECRET = "your_key_secret"

def api_get(url: str, params: dict = None, max_retries: int = 5) -> dict:
    """
    Perform a GET request with exponential backoff on HTTP 429.
    Raises after max_retries exhausted.
    """
    delay = 1.0  # initial back-off in seconds

    for attempt in range(1, max_retries + 1):
        response = requests.get(
            url,
            auth=(KEY_ID, KEY_SECRET),
            headers={"Accept": "application/json"},
            params=params,
        )

        if response.status_code == 429:
            # Optionally honour the reset time if provided
            reset_time = response.headers.get("X-CloudTalkAPI-ResetTime")
            if reset_time:
                wait = max(0, int(reset_time) - int(time.time())) + 1
            else:
                wait = delay + random.uniform(0, 1)

            print(
                f"[Attempt {attempt}/{max_retries}] Rate limited. "
                f"Retrying in {wait:.1f}s..."
            )
            time.sleep(wait)
            delay *= 2  # exponential back-off
            continue

        response.raise_for_status()
        return response.json()

    raise RuntimeError(f"Exceeded {max_retries} retries due to rate limiting.")


# Example usage
data = api_get(
    "https://my.cloudtalk.io/api/calls/index.json",
    params={"limit": 100, "page": 1},
)
print(data["responseData"]["itemsCount"], "total calls")

Rather than sleeping until an arbitrary back-off interval, parse X-CloudTalkAPI-ResetTime from the response headers and sleep until that Unix timestamp. This minimises wasted wait time when the window is about to reset anyway.

Requesting a Higher Limit

If your use case genuinely requires more than 60 requests per minute — for example, a real-time dashboard polling dozens of agents simultaneously — contact CloudTalk Support and include:

A description of your integration and why the current limit is insufficient.
The approximate sustained request rate you need (e.g. “~200 req/min during business hours”).
Your account identifier or API key prefix.

CloudTalk reviews limit-increase requests on a case-by-case basis and may apply a higher per-company threshold to your account.

Best Practices

Following these practices will help you stay well within the rate limit even as your integration scales.

Use the Bulk Endpoint

Contact actions packs up to 10 contact add/edit/delete operations into a single request — one unit of quota instead of ten.

Cache Read Results

Data like agent lists, phone numbers, and groups changes infrequently. Cache responses locally for a few minutes rather than fetching on every page load.

Narrow Result Sets with Filters

Apply the filters an endpoint documents — date_from, date_to and contact_id on call history, for instance. Smaller result sets require fewer pages and fewer total requests to export.

Header Quick Reference

Header	Example Value	How to Use
`X-CloudTalkAPI-Limit`	`60`	Confirms your account’s current rate limit ceiling.
`X-CloudTalkAPI-Remaining`	`0`	Requests left in the window. Slow down or pause as this approaches `0`.
`X-CloudTalkAPI-ResetTime`	`1712150460`	Sleep until this timestamp to resume at full quota.

Getting Started

API Concepts

Changelog

CloudTalk API Rate Limits, Headers, and Throttling

Default Limit

Rate-Limit Headers

Reading Headers with cURL

Implementing Retry Logic

Requesting a Higher Limit

Best Practices

Use the Bulk Endpoint

Cache Read Results

Narrow Result Sets with Filters

Header Quick Reference

​Default Limit

​Rate-Limit Headers

​Reading Headers with cURL

​Implementing Retry Logic

​Requesting a Higher Limit

​Best Practices

Use the Bulk Endpoint

Cache Read Results

Narrow Result Sets with Filters

​Header Quick Reference

Default Limit

Rate-Limit Headers

Reading Headers with cURL

Implementing Retry Logic

Requesting a Higher Limit

Best Practices

Header Quick Reference