---
source_url: https://www.pubnub.com/docs/analytics/usage-dashboards/rest-api
title: Insights API metrics
updated_at: 2026-09-30T07:20:08.000Z
---

# Insights API metrics

## Documentation index

To discover more PubNub resources:

1. Fetch [PubNub's llms.txt](https://www.pubnub.com/llms-full.txt) for a list of available pages in Markdown format.
2. Identify relevant URLs from that index.
3. Fetch the target pages.

Do not assume a path exists, always check the index first.

This page lists the metrics, top-metric categories, and supported periods for the PubNub Insights API. The Insights API requires Insights Premium. The API returns all metrics in UTC.

The Insights API is part of the [Admin API](https://www.pubnub.com/docs/admin-api/insights-introduction.md). The Admin API reference covers the request details: authentication with an Admin API key, endpoints, parameters, and response codes. Use this page to choose the metric names, category, and period you pass in a request.

| Endpoint | Returns | Admin API reference |
| --- | --- | --- |
| `GET /v2/insights` | General metrics for an account, app, or keyset | [getData](https://www.pubnub.com/docs/admin-api/get-data.md) |
| `GET /v2/insights/top` | Top channels and users for an account, app, or keyset | [getTopNData](https://www.pubnub.com/docs/admin-api/get-top-n-data.md) |

Metric names are case-sensitive. If you request a metric for a period it doesn't support, the Admin API returns `400`.

## Insights general metrics

These metrics go in the `metric[]` parameter of `GET /v2/insights`.

### Channel metrics

| Metric | Description |
| --- | --- |
| `unique_channels` | Unique channels in the selected period |
| `percent_unique_channels_with_messages` | Percentage of channels with messages out of all unique channels |
| `unique_channels_combination` | Unique channels, unique channels with messages, and unique channels with message chats |
| `channel_patterns` | Channel activity and performance filtered, sorted, and limited by your parameters |

### User metrics

| Metric | Description |
| --- | --- |
| `unique_users` | Unique users in the selected period |
| `percent_unique_users_with_messages` | Percentage of users with messages out of all unique users |
| `unique_users_combination` | Unique users, unique users with messages, and unique users with message chats |
| `new_vs_recurring_users` | New unique users and returning unique users compared with the preceding period |
| `unique_users_by_country` | Unique users per country in the selected period |

### Message metrics

| Metric | Description |
| --- | --- |
| `messages` | Messages published in the selected period |
| `message_by_country` | Messages per country in the selected period. Includes timestamps. |
| `top_10_message_types` | Top 10 message types for the selected period. Requires a JSON path in Messages Configuration if your payloads do not follow PubNub's message type conventions. |

### User duration and device metrics

| Metric | Description |
| --- | --- |
| `avg_user_duration` | Average time users stay connected per hour. For users with multiple connections to a channel, uses the longest session. |
| `unique_users_by_duration_timeframe` | Average connected time across channels for a specific hour |
| `publishes_by_device_type` | Publish calls by device type |
| `subscribers_by_device_type` | Subscribe calls by device type |
| `unique_users_by_device_type` | Unique users by device type |

### Channel patterns options

The `channel_patterns` metric groups channels by name pattern. The `filters`, `orderBy`, and `limit` parameters of `GET /v2/insights` apply to `channel_patterns` results.

* **filters** supports the operators `eq`, `neq`, `gt`, `lt`, `gte`, `lte`, `in`, `nin`, `startsWith`, `endsWith`, and `contains`.
* **orderBy** supports the fields `timestamp_value`, `count_messages`, `count_users`, `count_subscribers`, and `count_users_with_messages`.
* **limit** sets the number of `channel_patterns` records returned.

## Insights top metrics

These metrics go in the `metric[]` parameter of `GET /v2/insights/top`. Each request also needs a `category`. The `filters` parameter narrows results to specific channels or users and supports the operators `eq`, `neq`, `gt`, `lt`, `gte`, `lte`, `in`, `nin`, and `startsWith`.

| Metric | Description |
| --- | --- |
| `top_20_channels` | Top 20 channels for the selected period and category |
| `top_1000_channels` | Top 1000 channels for the selected period and category |
| `top_20_users` | Top 20 users for the selected period and category |
| `top_1000_users` | Top 1000 users for the selected period and category |
| `top_20_channels_with_user_duration` | Top 20 channels with average user duration and user counts by duration bucket |
| `top_1000_channels_with_user_duration` | Top 1000 channels with average user duration and user counts by duration bucket |

## Insights top metric categories

The `category` parameter of `GET /v2/insights/top` sets how top channels and users are ranked.

| Category | Description |
| --- | --- |
| `all` | All activity |
| `by_messages` | Ranked by message count |
| `by_chats` | Ranked by chat message count |
| `by_subscribers` | Ranked by subscriber count |
| `by_users_with_messages` | Ranked by users who published messages |
| `by_users_with_chats` | Ranked by users who published chat messages |
| `by_subscribed_channels` | Ranked by number of channels subscribed to (users only) |

## Supported periods for Insights metrics

Each metric supports only some values of the `period` parameter. These tables list which periods each metric accepts, including top metrics.

### Channel metric periods

| Metric | `hourly` | `daily` | `weekly` | `monthly` |
| --- | --- | --- | --- | --- |
| `unique_channels` | Yes | Yes | Yes | Yes |
| `percent_unique_channels_with_messages` | Yes | Yes | Yes | Yes |
| `unique_channels_combination` | Yes | Yes | Yes | Yes |
| `top_20_channels` | Yes | Yes | No | No |
| `top_1000_channels` | Yes | Yes | No | No |

### User metric periods

| Metric | `hourly` | `daily` | `weekly` | `monthly` |
| --- | --- | --- | --- | --- |
| `unique_users` | Yes | Yes | Yes | Yes |
| `percent_unique_users_with_messages` | Yes | Yes | Yes | Yes |
| `unique_users_combination` | Yes | Yes | Yes | Yes |
| `unique_users_by_country` | Yes | Yes | No | No |
| `new_vs_recurring_users` | No | Yes | Yes | Yes |
| `top_20_users` | Yes | Yes | No | No |
| `top_1000_users` | Yes | Yes | No | No |

### Message metric periods

| Metric | `hourly` | `daily` | `weekly` | `monthly` |
| --- | --- | --- | --- | --- |
| `messages` | Yes | Yes | Yes | Yes |
| `message_by_country` | Yes | Yes | No | No |
| `top_10_message_types` | Yes | Yes | No | No |

### User duration and device metric periods

| Metric | `hourly` | `daily` | `weekly` | `monthly` |
| --- | --- | --- | --- | --- |
| `avg_user_duration` | Yes | No | No | No |
| `unique_users_by_duration_timeframe` | Yes | No | No | No |
| `top_20_channels_with_user_duration` | Yes | No | No | No |
| `top_1000_channels_with_user_duration` | Yes | No | No | No |
| `publishes_by_device_type` | Yes | Yes | Yes | Yes |
| `subscribers_by_device_type` | Yes | Yes | Yes | Yes |
| `unique_users_by_device_type` | Yes | Yes | Yes | Yes |

## Related pages

* [Insights Introduction](https://www.pubnub.com/docs/admin-api/insights-introduction.md). Authenticate and call the Insights endpoints in the Admin API.
* [PubNub Insights](https://www.pubnub.com/docs/analytics/usage-dashboards/overview.md). See which plans include Insights Premium and what each dashboard shows.

Last updated at: 2026-09-30T07:20:08.000Z