> ## Documentation Index
> Fetch the complete documentation index at: https://developers.telnyx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Pagination, filtering, and sorting

> Traverse Telnyx REST API collections using endpoint-supported pagination, filter, and sort parameters.

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]`:

```http theme={null}
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:

```json theme={null}
{
  "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:

```http theme={null}
GET /v2/phone_numbers?filter[tag]=production
```

An endpoint can also declare repeated or array filters:

```http theme={null}
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:

```http theme={null}
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:

```text theme={null}
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](/docs/development/api-fundamentals/data-standards/parameters-fields) and [Rate limiting](/docs/development/api-fundamentals/reliability/rate-limiting).