Pagination, filtering, and sorting

Collection operations declare their supported query parameters in the API reference. Do not assume that every endpoint implements the same pagination, filtering, or sorting fields.

Page-based pagination

Endpoints using page-based pagination commonly accept page[number] and page[size]:

GET /v2/phone_numbers?page[number]=3&page[size]=20

Page numbering is 1-based. Omitting page[number] requests the first page. Endpoint references define default and maximum page sizes. A paginated response can include:

{
  "data": [],
  "meta": {
    "page_number": 3,
    "page_size": 20,
    "total_pages": 13,
    "total_results": 246
  }
}

When total_pages is present, continue until page_number reaches it. Otherwise, follow the endpoint’s documented links, cursors, or termination condition. Do not hard-code a global maximum page size.

Filtering

Filter syntax is endpoint-specific. An endpoint can expose scalar filters:

GET /v2/phone_numbers?filter[tag]=production

An endpoint can also declare repeated or array filters:

GET /v2/phone_numbers?filter[country_iso_alpha2][]=US&filter[country_iso_alpha2][]=CA

Use only filter names and operators documented for the selected operation.

Sorting

Endpoints that support sorting declare a sort parameter and allowed fields. A leading - commonly selects descending order:

GET /v2/connections?sort=connection_name
GET /v2/connections?sort=-created_at

Some operations support multiple sort fields. Follow the exact format shown in that operation’s reference.

Encode query parameters

Square brackets are part of the parameter name. HTTP clients normally percent-encode them automatically. When constructing a URL manually, preserve the equivalent encoded form:

page%5Bnumber%5D=3&page%5Bsize%5D=20

Operational guidance

Preserve a stable sort where supported so records are not skipped or repeated as a collection changes.
Bound concurrent page requests to remain within endpoint rate limits.
Restart pagination when filters or sorting change.
Treat pagination metadata as response data rather than predicting totals locally.

See Parameters and field names and Rate limiting.

​Page-based pagination

​Filtering

​Sorting

​Encode query parameters

​Operational guidance

Page-based pagination

Filtering

Sorting

Encode query parameters

Operational guidance