---
title: "Pagination"
description: "How list endpoints page their results, and how to walk a full result set."
---

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

# Pagination

Endpoints that return a list of resources are paginated. Use the `page` query parameter to move through the results:

```
GET /v2/contacts?page=2
```

Paginated responses wrap the results in a `data` array, alongside `links` and `meta` objects that describe where you are in the result set:

```json
{
  "data": [],
  "links": {
    "first": "https://app.touchsms.com.au/api/v2/contacts?page=1",
    "last": "https://app.touchsms.com.au/api/v2/contacts?page=8",
    "prev": null,
    "next": "https://app.touchsms.com.au/api/v2/contacts?page=2"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 8,
    "path": "https://app.touchsms.com.au/api/v2/contacts",
    "per_page": 50,
    "to": 50,
    "total": 400
  }
}
```

Rather than incrementing `page` yourself, follow `links.next` until it is `null`. This is the safest way to walk a full result set.

## Page size

The contacts and groups endpoints accept a `per_page` query parameter between `10` and `200`:

```
GET /v2/contacts?per_page=200
```

Other endpoints use a fixed page size and ignore `per_page`. Current defaults:

| Endpoint | Default page size | Accepts `per_page` |
|---|---|---|
| `/v2/contacts` | 50 | Yes (10 to 200) |
| `/v2/groups` | 50 | Yes (10 to 200) |
| `/v2/inbounds` | 100 | No |
| `/v2/optouts` | 15 | No |
| `/v2/optout-lists/{id}/optouts` | 50 | No |
| `/v2/webhook-subscriptions` | 25 | No |

Don't rely on these defaults staying fixed. Read `meta.per_page` from the response if your integration needs to know the page size it was served.

## Unpaginated lists

Some list endpoints return the full set in a `data` array with no `links` or `meta`, including [List templates](/api/templates/list/), [List sender IDs](/api/account/list-sender-ids/) and [List opt-out lists](/api/optout-lists/list/). Check for `meta` rather than assuming it is there.

Source: https://dev.touchsms.com.au/concepts/pagination/index.mdx