Aircall Help Center | Aircall API pagination and the 10,000 records retrieval limit

Aircall API pagination and the 10,000 records retrieval limit

When retrieving data using the Aircall API, list endpoints return results using pagination. This approach helps manage large datasets by splitting responses into multiple pages and providing navigation details for each page.

Pagination basics

Pagination details are included in the meta object of the API response. This object provides key information about the current dataset and navigation:

count: Number of items in the current page
total: Total number of items matching the query
current_page: Current page number
per_page: Number of items returned per page
next_page_link / previous_page_link: Links to navigate between pages

You can control pagination using the following query parameters:

page: Page number (default: 1)
per_page: Number of results per page (default: 20, maximum: 50)

Example

GET /v1/calls?page=2&per_page=50

10,000 records limit

For performance reasons, list endpoints in the Aircall API are limited to retrieving a maximum of 10,000 records per query, even when pagination is used.

This limit applies to endpoints that return collections of resources, including:

List all calls
List all contacts
Other similar listing endpoints

If more than 10,000 records match a request, the API will only return the first 10,000 results. Pages beyond this range are not accessible.

Important: Pagination parameters such as page and per_page do not bypass the 10,000-record limit.

Retrieving more than 10,000 records

To retrieve larger datasets, split your requests using available filters, such as time-based parameters.

For example, the /v1/calls endpoint supports:

from: Minimum call creation date (UNIX timestamp)
to: Maximum call creation date (UNIX timestamp)

By querying smaller time ranges, such as weekly or monthly intervals, each request can remain under the 10,000-record limit while still allowing full data retrieval.

Example

GET /v1/calls?from=<timestamp>&to=<timestamp>

Tip: Break down large queries into smaller time windows to ensure each request stays within the 10,000-record limit.

Additional notes

The maximum value for per_page is 50.
Pagination parameters do not allow access beyond 10,000 records.
Some endpoints, such as calls, may include additional constraints like limited historical availability.

Pagination basics

Pagination details are included in the meta object of the API response. This object provides key information about the current dataset and navigation:

count: Number of items in the current page
total: Total number of items matching the query
current_page: Current page number
per_page: Number of items returned per page
next_page_link / previous_page_link: Links to navigate between pages

You can control pagination using the following query parameters:

page: Page number (default: 1)
per_page: Number of results per page (default: 20, maximum: 50)

Example

GET /v1/calls?page=2&per_page=50

10,000 records limit

For performance reasons, list endpoints in the Aircall API are limited to retrieving a maximum of 10,000 records per query, even when pagination is used.

This limit applies to endpoints that return collections of resources, including:

List all calls
List all contacts
Other similar listing endpoints

If more than 10,000 records match a request, the API will only return the first 10,000 results. Pages beyond this range are not accessible.

Important: Pagination parameters such as page and per_page do not bypass the 10,000-record limit.

Retrieving more than 10,000 records

To retrieve larger datasets, split your requests using available filters, such as time-based parameters.

For example, the /v1/calls endpoint supports:

from: Minimum call creation date (UNIX timestamp)
to: Maximum call creation date (UNIX timestamp)

By querying smaller time ranges, such as weekly or monthly intervals, each request can remain under the 10,000-record limit while still allowing full data retrieval.

Example

GET /v1/calls?from=<timestamp>&to=<timestamp>

Tip: Break down large queries into smaller time windows to ensure each request stays within the 10,000-record limit.

Additional notes

The maximum value for per_page is 50.
Pagination parameters do not allow access beyond 10,000 records.
Some endpoints, such as calls, may include additional constraints like limited historical availability.