> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pgw.sipmicro.services/llms.txt
> Use this file to discover all available pages before exploring further.

# Page through lists

> Read long lists of bindings and users one page at a time with limit, after, and next.

Most lists in pgw are short and come back whole. Two can grow to thousands of items, so pgw returns them one page at a time:

* `GET /api/v1/bindings`, in binding key order
* `GET /api/v1/upstreams/{id}/users`, by domain and then username

## Read a list one page at a time

A request for a page takes these query parameters.

| Parameter | Description |
| - | - |
| `limit` | The largest number of items on the page, from 1 to 1000. The default is 100. |
| `after` | The `next` value of the previous page. Leave it out for the first page. |

**1. Get the first page**

```bash theme={null}
curl -s -H "Authorization: Bearer $PGW_API_KEY" "http://127.0.0.1:8080/api/v1/upstreams/Z--k3D5Qpnr6sFHF3YX2Fw/users?limit=2" | jq
```

Replace `Z--k3D5Qpnr6sFHF3YX2Fw` with your upstream's ID. The page holds the items and a `next` value.

```json theme={null}
{
  "items": [
    {
      "id": "nlE5NbZ1w3POfjv-CjZcLQ",
      "upstream_id": "Z--k3D5Qpnr6sFHF3YX2Fw",
      "username": "1001",
      "enabled": true,
      "last_seen_at": "2026-11-15T23:53:01Z",
      "created_at": "2026-11-15T23:53:01Z"
    },
    ...
  ],
  "next": "ADEwMDI"
}
```

**2. Get the next page**

Pass the previous page's `next` as `after`.

```bash theme={null}
curl -s -H "Authorization: Bearer $PGW_API_KEY" "http://127.0.0.1:8080/api/v1/upstreams/Z--k3D5Qpnr6sFHF3YX2Fw/users?limit=2&after=ADEwMDI"
```

**3. Stop at the last page**

Repeat the previous step until `next` is empty.

```json theme={null}
{"items":[{"id":"GM4FEMVzVL2K3zLlErV8cg","upstream_id":"Z--k3D5Qpnr6sFHF3YX2Fw","username":"1005","enabled":true,"last_seen_at":"2026-11-15T23:53:01Z","created_at":"2026-11-15T23:53:01Z"}],"next":""}
```

Pass `next` back unchanged. A `limit` outside 1 to 1000 gets `400`. For users, an `after` that isn't the `next` of a page of users also gets `400`, with the error `after must be the next of a page of users`.

## Lists without pages

The other lists return every item in one response, as `{"items": [...]}`, with no `next`. `GET /api/v1/push-events` takes `limit`, 100 by default, and returns only the newest events. `GET /api/v1/register-bans` returns `{"bans": [...]}`.

## Next steps

> [card] [Read the push log](https://docs.pgw.sipmicro.services/push-log.md)
>
> List the newest push events for your tenant.

> [card] [Handle errors](https://docs.pgw.sipmicro.services/api/errors.md)
>
> Read the error body when a request for a page fails.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.