# Usage

<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->

Zoom APIs use pagination to organize large response datasets into manageable chunks. This approach helps you efficiently handle substantial data payloads when making `GET` requests that list large numbers of resources.

## Response limits

The number of items returned per page varies based on the API and data retrieval level:

-   Light data retrieval: Up to 300 items per page
-   Heavy data retrieval: Up to 30, 50, or 100 items per page, depending on the specific API

For details on light and heavy APIs, see the [Rate limits](/docs/api/rate-limits) documentation.

## Using `next_page_token`

Most Zoom APIs, including [List Meeting participants](/docs/api/accounts/#tag/dashboards/GET/metrics/meetings/{meetingId}/participants) and [List Webinars](/docs/api/accounts/#tag/dashboards/GET/metrics/webinars/{webinarId}/participants), use the `next_page_token` parameter for pagination.

-   If the initial API query returns a complete response, the `next_page_token` value will be an empty string.
-   A non-empty `next_page_token` value (e.g., `"abc3445rg"`) indicates that additional results are available.

To retrieve additional responses, include the `next_page_token` value in subsequent API requests using the same query parameters.

### Step through a paginated request

This example walks through the [List Users](/docs/api/users/#tag/users/GET/users) API. The account has three users, and we request two per page so the list spans two pages.

**Step 1 - request the first page.** Send the initial request with your chosen `page_size`. Do not include `next_page_token` yet.

```shell
curl --request GET \
  --url 'https://api.zoom.us/v2/users?status=active&page_size=2' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```

The response returns the first two users and a non-empty `next_page_token`, which signals that more results are available:

```json
{
    "page_size": 2,
    "page_count": 2,
    "total_records": 3,
    "next_page_token": "Tva2K9uF6sQmPq8nR3wXcLdYbZ7hJ1gE0",
    "users": [
        {
            "id": "KDcuGImsQZ4_pZHC3clH1g",
            "first_name": "Jill",
            "last_name": "Chill",
            "email": "jchill@example.com",
            "type": 2,
            "status": "active"
        },
        {
            "id": "g7b6al3WSVassBHsbxfHDw",
            "first_name": "Htrue",
            "last_name": "Holmes",
            "email": "hholmes@example.com",
            "type": 1,
            "status": "active"
        }
    ]
}
```

**Step 2 - request the next page.** Copy the `next_page_token` from the response and add it to the next request. Keep every other query parameter (here `status` and `page_size`) identical to the first request.

```shell
curl --request GET \
  --url 'https://api.zoom.us/v2/users?status=active&page_size=2&next_page_token=Tva2K9uF6sQmPq8nR3wXcLdYbZ7hJ1gE0' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```

This response returns the final user. The `next_page_token` is now an empty string, which means you have reached the last page:

```json
{
    "page_size": 2,
    "page_count": 2,
    "total_records": 3,
    "next_page_token": "",
    "users": [
        {
            "id": "8sdf-3jfksdfwe0Sd9fj2w",
            "first_name": "Aldo",
            "last_name": "Apple",
            "email": "aapple@example.com",
            "type": 1,
            "status": "active"
        }
    ]
}
```

Repeat step 2, passing each response's `next_page_token` into the next request, until the token comes back empty.

### Automate the loop: list all users

The previous walkthrough maps directly to a loop. Keep requesting pages, feeding each `next_page_token` into the next call, until the token is empty:

```javascript
const axios = require("axios");

async function getAllUsers(baseUrl, accessToken) {
    let allUsers = [];
    let nextPageToken = "";

    while (true) {
        const headers = {
            Authorization: `Bearer ${accessToken}`,
            "Content-Type": "application/json",
        };

        const params = { page_size: 300 };
        if (nextPageToken) {
            params.next_page_token = nextPageToken;
        }

        try {
            const response = await axios.get(baseUrl, { headers, params });
            const data = response.data;

            allUsers = allUsers.concat(data.users || []);
            nextPageToken = data.next_page_token || "";

            if (!nextPageToken) {
                break;
            }
        } catch (error) {
            console.error("Error fetching users:", error.message);
            break;
        }
    }

    return allUsers;
}

// Usage
const baseUrl = "https://api.zoom.us/v2/users";
const accessToken = "YOUR_ACCESS_TOKEN";

getAllUsers(baseUrl, accessToken)
    .then((users) => console.log(`Total users retrieved: ${users.length}`))
    .catch((error) => console.error("Error:", error.message));
```

```python
import requests

def get_all_users(base_url, access_token):
    all_users = []
    next_page_token = ''

    while True:
        headers = {
            "Authorization": f"Bearer {access_token}",
            "Content-Type": "application/json"
        }

        params = {"page_size": 300}
        if next_page_token:
            params["next_page_token"] = next_page_token

        response = requests.get(base_url, headers=headers, params=params)
        data = response.json()

        all_users.extend(data.get('users', []))

        next_page_token = data.get('next_page_token', '')
        if not next_page_token:
            break

    return all_users

# Usage
base_url = "https://api.zoom.us/v2/users"
access_token = "YOUR_ACCESS_TOKEN"
users = get_all_users(base_url, access_token)
print(f"Total users retrieved: {len(users)}")
```

## Legacy pagination: page numbers

Some Zoom APIs, like [List Users](/docs/api/users/#tag/users/GET/users), support pagination using `page_size` and `page_number` parameters. However, this method is being phased out in favor of `next_page_token`.

-   `page_size` - number of records to return per page
-   `page_number` - specific page to retrieve

We recommend setting these values based on your needs, rather than relying on default values.

With page numbers, you request the first page, then increment `page_number` until you reach `page_count`. Using the same three-user account as before:

```shell
# Page 1
curl --request GET \
  --url 'https://api.zoom.us/v2/users?status=active&page_size=2&page_number=1' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```

The response reports `page_count`, which tells you how many pages exist:

```json
{
    "page_count": 2,
    "page_number": 1,
    "page_size": 2,
    "total_records": 3,
    "users": [
        {
            "id": "KDcuGImsQZ4_pZHC3clH1g",
            "email": "jchill@example.com",
            "type": 2,
            "status": "active"
        },
        {
            "id": "g7b6al3WSVassBHsbxfHDw",
            "email": "hholmes@example.com",
            "type": 1,
            "status": "active"
        }
    ]
}
```

Because `page_number` (1) is less than `page_count` (2), request the next page by incrementing `page_number`:

```shell
# Page 2
curl --request GET \
  --url 'https://api.zoom.us/v2/users?status=active&page_size=2&page_number=2' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```

Once `page_number` equals `page_count`, you have retrieved every page.

### Automate the loop: list users with page numbers

```javascript
const axios = require("axios");

async function getAllUsers(baseUrl, accessToken) {
    let allUsers = [];
    let pageNumber = 1;
    const pageSize = 300;

    while (true) {
        const headers = {
            Authorization: `Bearer ${accessToken}`,
            "Content-Type": "application/json",
        };

        const params = {
            page_size: pageSize,
            page_number: pageNumber,
        };

        try {
            const response = await axios.get(baseUrl, { headers, params });
            const data = response.data;

            allUsers = allUsers.concat(data.users || []);

            if (pageNumber >= data.page_count) {
                break;
            }

            pageNumber++;
        } catch (error) {
            console.error("Error fetching users:", error.message);
            break;
        }
    }

    return allUsers;
}

// Usage
const baseUrl = "https://api.zoom.us/v2/users";
const accessToken = "YOUR_ACCESS_TOKEN";

getAllUsers(baseUrl, accessToken)
    .then((users) => console.log(`Total users retrieved: ${users.length}`))
    .catch((error) => console.error("Error:", error.message));
```

```python
import requests

def get_all_users(base_url, access_token):
    all_users = []
    page_number = 1
    page_size = 300

    while True:
        headers = {
            "Authorization": f"Bearer {access_token}",
            "Content-Type": "application/json"
        }

        params = {
            "page_size": page_size,
            "page_number": page_number
        }

        response = requests.get(base_url, headers=headers, params=params)
        data = response.json()

        all_users.extend(data.get('users', []))

        if page_number >= data.get('page_count', 0):
            break

        page_number += 1

    return all_users

# Usage
base_url = "https://api.zoom.us/v2/users"
access_token = "YOUR_ACCESS_TOKEN"
users = get_all_users(base_url, access_token)
print(f"Total users retrieved: {len(users)}")
```