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

# Pagination

> How page-based pagination works in the Zeeg API. Use the count and page query parameters and walk through results with the nextPage cursor.

Most list endpoints in the Zeeg API return paginated results. Instead of returning every record at once, responses are split into pages that you can iterate through.

## Parameters

Every paginated endpoint accepts the following query parameters:

| Parameter | Type    | Default | Description                                   |
| --------- | ------- | ------- | --------------------------------------------- |
| `count`   | integer | `20`    | Number of items per page. Min `1`, max `100`. |
| `page`    | integer | `1`     | The page number to retrieve (1-indexed).      |

<Warning>
  The `/organizations/users` endpoint uses `per_page` instead of `count`. All other paginated endpoints use `count`.
</Warning>

## Response structure

Paginated responses include a `collection` array with the requested items and a `pagination` object with metadata for navigating between pages.

```json theme={null}
{
  "collection": [
    { "...": "..." }
  ],
  "pagination": {
    "total": 42,
    "count": 20,
    "totalPages": 3,
    "previousPage": "/v2/scheduled-events?page=1",
    "currentPage": 2,
    "nextPage": "/v2/scheduled-events?page=3"
  }
}
```

<ResponseField name="pagination.total" type="integer">
  The total number of items across all pages.
</ResponseField>

<ResponseField name="pagination.count" type="integer">
  The number of items returned in the current page.
</ResponseField>

<ResponseField name="pagination.totalPages" type="integer">
  The total number of pages available.
</ResponseField>

<ResponseField name="pagination.previousPage" type="string | null">
  The path to the previous page of results. `null` when you are on the first page.
</ResponseField>

<ResponseField name="pagination.currentPage" type="integer">
  The current page number.
</ResponseField>

<ResponseField name="pagination.nextPage" type="string | null">
  The path to the next page of results. `null` when you are on the last page.
</ResponseField>

## Iterating through pages

Use `nextPage` to walk through all pages until it returns `null`.

<CodeGroup>
  ```bash curl theme={null}
  # Fetch page 1
  curl "https://api.zeeg.me/v2/scheduled-events?count=20&page=1" \
    -H "Authorization: Bearer YOUR_TOKEN"

  # Fetch the next page
  curl "https://api.zeeg.me/v2/scheduled-events?count=20&page=2" \
    -H "Authorization: Bearer YOUR_TOKEN"
  ```

  ```python Python theme={null}
  import requests

  BASE_URL = "https://api.zeeg.me/v2"
  headers = {"Authorization": "Bearer YOUR_TOKEN"}

  page = 1
  all_events = []

  while True:
      response = requests.get(
          f"{BASE_URL}/scheduled-events",
          headers=headers,
          params={"count": 20, "page": page},
      )
      data = response.json()
      all_events.extend(data["collection"])

      if data["pagination"]["nextPage"] is None:
          break

      page += 1

  print(f"Fetched {len(all_events)} events in total.")
  ```

  ```javascript JavaScript theme={null}
  const BASE_URL = "https://api.zeeg.me/v2";
  const headers = { Authorization: "Bearer YOUR_TOKEN" };

  async function fetchAllEvents() {
    let page = 1;
    const allEvents = [];

    while (true) {
      const res = await fetch(
        `${BASE_URL}/scheduled-events?count=20&page=${page}`,
        { headers }
      );
      const data = await res.json();
      allEvents.push(...data.collection);

      if (data.pagination.nextPage === null) break;
      page++;
    }

    return allEvents;
  }
  ```
</CodeGroup>

<Tip>
  Use a smaller `count` (e.g. `10`) if you need faster individual responses, or a larger `count` (up to `100`) to reduce the total number of requests.
</Tip>