---
title: "Zoom data source plugin for Grafana"
description: "Query Zoom meeting quality, room health, user activity and phone device status from Grafana. Zoom data source plugin for Grafana by crestdata."
---

> This is the Markdown version of https://grafana.com/grafana/plugins/crestdata-zoom-datasource/

# Zoom

- Developer: crestdata
- Version: 1.0.4
- [Change log](https://grafana.com/grafana/plugins/crestdata-zoom-datasource/changelog.md)

![Configuration Editor](https://grafana.com/api/plugins/crestdata-zoom-datasource/versions/1.0.4/images/img/config_editor.png)

![Query Editor](https://grafana.com/api/plugins/crestdata-zoom-datasource/versions/1.0.4/images/img/query_editor.png)

# Zoom Data Source Plugin for Grafana

## Description

The **Zoom Data Source Plugin** is a Grafana backend datasource plugin that integrates with Zoom's REST API v2 to query meeting metrics, QoS data, user activity, Zoom Room health, and phone device status from Grafana dashboards, Explore, and Alerting.

Zoom is a cloud communications platform that provides video meetings, room systems, user management, and phone services. This plugin provides visibility into Zoom account activity by allowing users to explore meetings, meeting quality, room health, user listings, and phone device status directly within Grafana.

### Features

- Query and visualize meeting details, meeting QoS, participant QoS, Zoom Room health, user activity, and phone device status from Grafana
- Support for multiple Zoom data categories including Meetings, Zoom Rooms, Users, and Phones
- Live and historical meeting analysis, including aggregated and time-series QoS views
- Automatic 30-day chunking for past meeting queries to comply with Zoom API time-window limits
- Pre-built dashboards for Zoom overview, meeting quality, user details, and Zoom Room monitoring
- Automatic retry handling for transient API failures, including rate limits and server-side errors
- Compatibility with Grafana dashboards, Explore, and Alerting workflows

### Compatibility

| Component      | Version / Detail                                                              |
| -------------- | ----------------------------------------------------------------------------- |
| Grafana        | >= 12.3.0                                                                     |
| Zoom API       | REST API v2                                                                   |
| Authentication | Server-to-Server OAuth (Account ID, Client ID, Client Secret)                 |
| Zoom Account   | Pro, Business, or Enterprise (Business+ recommended for Heavy/Dashboard APIs) |

## Visuals

### Configuration Editor

![Configuration Editor](https://raw.githubusercontent.com/jignesh-crest/crestdata-grafana-plugin-artifacts/refs/heads/main/crestdata-zoom-datasource/config_editor.png)

### Query Editor

![Query Editor](https://raw.githubusercontent.com/jignesh-crest/crestdata-grafana-plugin-artifacts/refs/heads/main/crestdata-zoom-datasource/query_editor.png)

## Installation

### Requirements

- Grafana >= 12.3.0

- A Zoom Pro, Business, or Enterprise account (Business+ recommended for Heavy/Dashboard APIs)

- Admin-level access to the Zoom App Marketplace to create a Server-to-Server OAuth app

- The following OAuth scopes granted to the app:

  - `dashboard_meetings:read:admin`
  - `dashboard_zoomrooms:read:admin`
  - `user:read:admin`
  - `room:read:admin`
  - `phone:read:admin`
  - `meeting:read:admin`

### Obtaining Zoom Credentials

1. Sign in to the [Zoom App Marketplace](https://marketplace.zoom.us/) as an account admin.

2. Click **Develop -> Build App**.

3. Select **Server-to-Server OAuth** and click **Create**.

4. Provide an app name such as `Grafana Zoom Data Source` and click **Create**.

5. On the **App Credentials** tab, copy the following values:

   - **Account ID**
   - **Client ID**
   - **Client Secret**

6. On the **Information** tab, fill in the required company and developer contact fields.

7. On the **Scopes** tab, add all required scopes listed above.

8. On the **Activation** tab, click **Activate your app**.

### Install the Plugin

Install the plugin from the [Grafana Plugin Catalog](https://grafana.com/grafana/plugins/) or using the Grafana CLI:

```bash
grafana cli plugins install crestdata-zoom-datasource
```

After installation, restart the Grafana server for the plugin to be loaded.

### Configure the Data Source

1. In Grafana, navigate to **Connections > Data Sources > Add data source**.
2. Search for **Zoom** and select it.
3. Fill in the required configuration fields:

| Name            | Type           | Required | Description                                                             |
| --------------- | -------------- | -------- | ----------------------------------------------------------------------- |
| Account ID      | String         | Yes      | Zoom account identifier from the Server-to-Server OAuth app credentials |
| Client ID       | String         | Yes      | OAuth Client ID of the Server-to-Server OAuth app                       |
| Client Secret   | Secured String | Yes      | OAuth Client Secret, stored securely by Grafana                         |
| API Base URL    | String         | No       | Zoom REST API base URL; defaults to `https://api.zoom.us/v2`            |
| OAuth Token URL | String         | No       | Zoom OAuth token endpoint; defaults to `https://zoom.us/oauth/token`    |

1. Click **Save & Test** to validate the credentials and required Zoom API access.

## Usage

### Query Editor

Once the data source is configured, you can create panels using the query editor with the following parameters:

| Parameter      | Type     | Options                             | Default  | Description                                                            |
| -------------- | -------- | ----------------------------------- | -------- | ---------------------------------------------------------------------- |
| Entity         | Dropdown | Meetings, Zoom Rooms, Users, Phones | Meetings | Top-level Zoom data category to query                                  |
| Query Type     | Dropdown | Varies by selected entity           | Details  | Specific query mode for the selected entity                            |
| Live Meetings  | Toggle   | Enabled, Disabled                   | Disabled | Fetch live meetings and ignore the selected time range where supported |
| Meeting ID     | String   | NA                                  | NA       | Optional for QoS queries; when blank, the plugin iterates all meetings |
| Participant ID | String   | NA                                  | NA       | Optional filter for participant-level QoS queries                      |
| Room ID        | String   | NA                                  | NA       | Required for `Zoom Rooms > Associated Meetings`                        |

**Meetings**

| Query Type             | Time Range           | Required Fields                         | Output                                                                   |
| ---------------------- | -------------------- | --------------------------------------- | ------------------------------------------------------------------------ |
| Details                | Yes (or Live toggle) | NA                                      | Table of meetings with host, participants, duration, and quality ratings |
| Meeting QOS            | Yes (or Live toggle) | `meetingId` (optional)                  | Table with one row per meeting and averaged QoS metrics                  |
| Meeting QOS Series     | Yes (or Live toggle) | `meetingId` (optional)                  | Time series of QoS metrics per timestamp                                 |
| Participant QOS        | Yes (or Live toggle) | `meetingId`, `participantId` (optional) | Table with one row per participant                                       |
| Participant QOS Series | Yes (or Live toggle) | `meetingId`, `participantId` (optional) | Time series of raw per-sample metrics per participant                    |

When **Meeting ID** is blank for a QoS query, the plugin iterates all meetings in the selected panel time range and concatenates the results.

**Zoom Rooms**

| Query Type          | Time Range | Required Fields     | Output                                                                                      |
| ------------------- | ---------- | ------------------- | ------------------------------------------------------------------------------------------- |
| Details             | No         | NA                  | Table of all Zoom Rooms with health, status, and components                                 |
| Associated Meetings | Yes        | `roomId` (required) | Table of past meetings for the room; any in-progress live meeting is included automatically |

**Users / Phones**

Both expose **Details**:

- **Users** returns a table listing users, including license type, department, and activity fields
- **Phones** returns a table listing account-wide phone device status with site and assignee mapping

### Time Range Handling

Past meeting queries are split into **30-day chunks** to stay within Zoom's API time-window limits. The plugin merges paginated responses transparently, so no manual action is required from the user.

| Scenario                        | Behaviour                                    |
| ------------------------------- | -------------------------------------------- |
| Live toggle enabled             | Fetches live meetings; date range is ignored |
| Past meetings, range <= 30 days | Single date-range request                    |
| Past meetings, range > 30 days  | Split into 30-day chunks, results merged     |
| Users / Phones details          | Account-wide listings; time range ignored    |

### Error Handling and Retry Strategy

Retries are performed automatically for transient failures:

- HTTP 429 (rate limited) while honoring the `Retry-After` header
- HTTP 5xx responses with exponential backoff
- Network or connection-level errors with exponential backoff
- One-time token refresh on applicable `401 Unauthorized` query failures

**Max retry attempts:** 3. Non-retryable errors such as most HTTP 4xx responses are returned immediately.

Common issues:

| Symptom                              | Likely Cause                                                    | Fix                                                              |
| ------------------------------------ | --------------------------------------------------------------- | ---------------------------------------------------------------- |
| `Health check failed` on Save & Test | Account ID, Client ID, or Client Secret is missing or incorrect | Fill in all three fields and verify the values in the Zoom app   |
| `token request returned 401`         | Wrong Client ID / Secret or inactive app                        | Re-check credentials and ensure the app is activated             |
| `403` with insufficient scopes       | OAuth app is missing required scopes                            | Add the missing scopes in the Zoom app and retry                 |
| `rate limited (429)`                 | Heavy-class quota is shared across the Zoom account             | Stagger dashboard refreshes; the plugin will honor `Retry-After` |

### Pre-built Dashboards

The plugin ships with four pre-built dashboards for quick visualization and monitoring of Zoom environments.

| Setting              | Value         |
| -------------------- | ------------- |
| Default time range   | Last 24 hours |
| Auto-refresh         | Enabled       |
| Datasource selection | Zoom          |

**1. Zoom Overview** — Provides a high-level summary of Zoom activity, including:

- Meeting counts and activity overview
- Quality ratings
- Active room status

**2. Zoom Meeting Quality** — Displays per-meeting and per-participant QoS insights, including:

- Aggregated meeting QoS metrics
- Participant-level QoS metrics
- Time-series quality analysis

**3. Zoom User Details** — Displays user-level account insights, including:

- Active, inactive, pending, and all user listings
- License type details
- Department and activity information

**4. Zoom Rooms** — Provides visibility into Zoom Room environments, including:

- Room health and status
- Room component details
- Associated meeting activity

### Limitations

**API Limitation:** Zoom dashboard APIs impose time-window restrictions on historical meeting queries, and account-wide listing endpoints such as Users and Phones do not use the Grafana time range. In addition, Heavy-class Zoom API quotas are shared across the entire Zoom account.

**Design Adaptation** To accommodate these constraints, the plugin splits eligible historical meeting queries into 30-day chunks, merges the results automatically, exposes a live query mode where supported, and treats account-wide listing endpoints as time-range-independent queries.

## Support

For issues, questions, or feature requests, please open an issue in this repository.

## Roadmap

See the open issues for a list of proposed features and known issues.

## Contributing

Contributions are welcome! To get started with development:

```bash
cd crestdata-zoom-datasource

# Frontend
npm install
npm run dev        # development mode with watch
npm run build      # production build

# Backend
mage -v            # build backend binaries

# Tests
npm run test       # frontend tests (Jest)
npm run test:ci    # CI mode
go test ./...      # backend tests

# Linting
npm run lint
npm run lint:fix

# Local Grafana instance (Docker)
npm run server

# E2E tests (Playwright)
npm run e2e
```

Before submitting a pull request:

1. Run the linter and ensure all tests pass.
2. Validate the plugin using the [Grafana Plugin Validator](https://github.com/grafana/plugin-validator).
3. Ensure any changes to `plugin.json` are intentional — a Grafana server restart is required after such changes.

## Authors and Acknowledgment

Developed by [Crest Data](https://www.crestdata.ai/).

## License

This plugin is distributed under EULA [LICENSE](https://gist.github.com/jignesh-crest/9021da50bc6625b6e06118d0f05e469d).

## References

- [Zoom API Reference](https://developers.zoom.us/docs/api/rest/reference/zoom-api/methods/)
- [Zoom Dashboard API](https://developers.zoom.us/docs/api/rest/reference/zoom-api/methods/#tag/Dashboards)
- [Zoom OAuth (Server-to-Server)](https://developers.zoom.us/docs/internal-apps/)
- [Grafana Plugin Development](https://grafana.com/developers/plugin-tools/)
- [Grafana Data Source Plugin Guide](https://grafana.com/developers/plugin-tools/tutorials/build-a-data-source-plugin)