---
source_url: https://www.pubnub.com/docs/pubnub-insights/api-overview
title: Insights API Overview
updated_at: 2026-05-18T12:48:46.813Z
---

> Documentation Index
> For a curated overview of PubNub documentation, see: https://www.pubnub.com/docs/llms.txt
> For the full list of all documentation pages, see: https://www.pubnub.com/docs/llms-full.txt


# Insights API Overview

:::note Availability
PubNub Insights metrics are available through API only in Insights Premium.
:::

You can view Insights in the [Admin Portal](https://admin.pubnub.com/). If you use [Premium](https://www.pubnub.com/docs/pubnub-insights/basics#availability), you can also get app metrics with the [Insights API](https://www.pubnub.com/docs/pubnub-insights/api).

## Insights metrics

You can request two sets of Insights metrics:

* [Metrics](https://www.pubnub.com/docs/pubnub-insights/api#metrics) ([/insights](https://www.pubnub.com/docs/pubnub-insights/api) endpoint)
* [Top metrics](https://www.pubnub.com/docs/pubnub-insights/api#top-metrics) ([/insights/top](https://www.pubnub.com/docs/pubnub-insights/api) endpoint)

:::note UTC timezone for metrics
PubNub Insights API returns all metrics in the UTC timezone.
:::

### Metrics

The [/insights](https://www.pubnub.com/docs/pubnub-insights/api) endpoint returns these metrics.

* Channels

| Metric | Description |
| --- | --- |
| `percent_unique_channels_with_messages` | The percentage of channels with messages out of all unique channels in the selected period and date range. |
| `unique_channels` | Unique channels in the selected period. |
| `unique_channels_combination` | Unique channels, unique channels with messages, and unique channels with message chats (for the [Chat use case](https://www.pubnub.com/docs/pubnub-insights/basics#access)). Message chats are text messages. |

* Users

| Metric | Description |
| --- | --- |
| `new_vs_recurring_users` | Number of new unique users and returning unique users (compared with the preceding period) for the selected period and date range. |
| `percent_unique_users_with_messages` | The percentage of users with messages out of all unique users in the selected period and date range. |
| `unique_users` | Unique users in the selected period. |
| `unique_users_by_country` | Unique users per country in the selected period. |
| `unique_users_combination` | Unique users, unique users with messages, and unique users with message chats (for the [Chat use case](https://www.pubnub.com/docs/pubnub-insights/basics#access)). Message chats are text messages. |

* Messages

| 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. Define types by setting the JSON path in Messages > Dashboard Settings. |

* User Duration & Devices

| Metric | Description |
| --- | --- |
| `avg_user_duration` | Average time users stay connected per hour. For users with multiple connections to a channel, the API 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 in the selected period. |
| `subscribers_by_device_type` | Subscribe calls by device type in the selected period. |
| `unique_users_by_device_type` | Unique users by device type in the selected period. |

* Channel patterns

| Metric | Description |
| --- | --- |
| `channel_patterns` | Channel activity and performance for a selected period. Filter, limit, and sort channel data to analyze engagement and activity. |

#### Parameters

* `filter`: Filter by criteria (for example, channel name). Operators include `startsWith`, `eq`.
* `limit`: Number of results to return.
* `orderBy`: Sort by a field (for example, `timestamp_value`, `count_messages`) in ascending or descending order.

### Top metrics

Metrics available on the [/insights/top](https://www.pubnub.com/docs/pubnub-insights/api) endpoint.

* Channels

| Metric | Description |
| --- | --- |
| `top_20_channels` | Top 20 channels for the selected period, category, and date range. |
| `top_1000_channels` | Top 1000 channels for the selected period, category, and date range. |
| `top_20_channels_with_user_duration` | Top 20 channels with average user duration & number of users by duration for the selected period, category, and date range. |
| `top_1000_channels_with_user_duration` | Top 1000 channels with average user duration & number of users by duration for the selected period, category, and date range. |

* Users

| Metric | Description |
| --- | --- |
| `top_20_users` | Top 20 users for the selected period, category, and date range. |
| `top_1000_users` | Top 1000 users for the selected period, category, and date range. |

#### Categories

Top metrics use categories in requests and responses.

#### Requests

Group top metrics by:

* `all`
* `by_chats`
* `by_messages`
* `by_subscribers`
* `by_users_with_chats`
* `by_subscribed_channels`
* `by_users_with_messages`

#### Responses

For `period=hourly` or `period=daily`, responses include:

| Returned category | Description | `top_20_channels` | `top_1000_channels` | `top_20_users` | `top_1000_users` | `top_20_channels_with_user_duration` | `top_1000_channels_with_user_duration` |
| --- | --- | --- | --- | --- | --- | --- | --- |
| `count_messages` | Number of messages published. | Yes | Yes | Yes | Yes | No | No |
| `count_subscribers` | Number of subscribers for the channel. | Yes | Yes | No | No | No | No |
| `count_users_with_messaging` | Number of unique users publishing messages within the channel. | Yes | Yes | No | No | No | No |
| `count_chat` | Number of messages (that contain textual information) published. | Yes | Yes | Yes | Yes | No | No |
| `count_users_with_chat` | Number of unique users publishing messages within the channel. | Yes | Yes | No | No | No | No |
| `count_channels_subscribed_to` | Number of channels the user has subscribed to. | No | No | Yes | Yes | No | No |
| `timestamp_value` | Timestamp of the hour or day for which the top 20 / 1000 channels / users have been requested. This timestamp is in UTC. | Yes | Yes | Yes | Yes | No | No |
| `avg_user_duration` | On average how long users stay connected to the channel. | No | No | No | No | Yes | Yes |
| `user_duration_0_5_min` | Number of users that stay connected to the channel for 0-5 minutes. | No | No | No | No | Yes | Yes |
| `user_duration_5_10_min` | Number of users that stay connected to the channel for 5-10 minutes. | No | No | No | No | Yes | Yes |
| `user_duration_10_15_min` | Number of users that stay connected to the channel for 10-15 minutes. | No | No | No | No | Yes | Yes |
| `user_duration_15_20_min` | Number of users that stay connected to the channel for 15-20 minutes. | No | No | No | No | Yes | Yes |
| `user_duration_20_30_min` | Number of users that stay connected to the channel for 20-30 minutes. | No | No | No | No | Yes | Yes |
| `user_duration_30_40_min` | Number of users that stay connected to the channel for 30-40 minutes. | No | No | No | No | Yes | Yes |
| `user_duration_40_50_min` | Number of users that stay connected to the channel for 40-50 minutes. | No | No | No | No | Yes | Yes |
| `user_duration_50_60_min` | Number of users that stay connected to the channel for 50-60 minutes. | No | No | No | No | Yes | Yes |

Example: To get the top 20 channels by messages, use the `by_messages` category.

## Limitations

To keep responses fast, the API limits data per call. Limits depend on:

* Type of metric (for example, `unique_channels`)
* Time period (`period` parameter, for example, `hourly`)

:::tip API specification
For the full Open API specification, technical information on authentication, examples of sample calls, responses, and error codes, refer to the [REST API documentation](https://www.pubnub.com/docs/pubnub-insights/api).
:::

### Period restrictions for metrics

You can retrieve data for some metrics only in selected periods.

* Channels

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

* Users

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

* Messages

| Metric name | `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 & Devices

| Metric name | `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 |