Insights API Overview
Availability
PubNub Insights metrics are available through API only in Insights Premium.
Besides accessing Insights metrics through Admin Portal, Premium users can access their apps' metrics using the Insights API.
Insights metrics
There are two sets of Insights metrics for which you can request data:
- Metrics (
/insightsendpoint) - Top metrics (
/insights/topendpoint)
UTC timezone for metrics
PubNub Insights API returns all metrics in the UTC timezone.
Metrics
Metrics available on the /insights endpoint.
- Channels
| Metric | Description |
|---|---|
percent_unique_channels_with_messages | The percentage of channels with messages out of all unique channels in the specified period and date range. |
unique_channels | Number of unique channels for the specified period and date range. |
unique_channels_combination | Unique channels, unique channels with messages, and unique channels with message chats (for the Chat use case). Message chats refer to any messages that contain text information. |
- Users
| Metric | Description |
|---|---|
new_vs_recurring_users | Number of new unique users and returning unique users (compared with the preceding period) for the specified period and date range. |
percent_unique_users_with_messages | The percentage of users with messages out of all unique users in the specified period and date range. |
unique_users | Number of unique users for the specified period and date range. |
unique_users_by_country | Number of unique users across all channels per country for the specified period and date range. |
unique_users_combination | Unique users, unique users with messages, and unique users with message chats (for the Chat use case). Message chats refer to any messages that contain text information. |
- Messages
| Metric | Description |
|---|---|
messages | Number of messages published across all channels for the specified period and date range. |
message_by_country | Total number of messages published across all channels per country for the specified period and date range. This metric also shows message timestamps. |
top_10_message_types | Top 10 types of messages for the specified period and date range. The message types can be defined by updating the JSON path in the Messages section of the Dashboard Settings in the Insights dashboard. |
- User Duration & Devices
| Metric | Description |
|---|---|
avg_user_duration | Data for a subscribe key on how long (on average) users stay connected to all channels per hour. If one user has multiple connections to a specific channel, Insight API will provide metrics for the duration of the longest connection between this user and channel. |
unique_users_by_duration_timeframe | Data showing how long users stay connected to channels or events on average. This average is calculated across all channels for a specific hour. |
publishes_by_device_type | Number of Publish calls by device type for a subscribe key in the specified period. |
subscribers_by_device_type | Number of Subscribe calls by device type for a subscribe key in the specified period. |
unique_users_by_device_type | Number of unique users by device type for a subscribe key in the specified period. |
- Channel patterns
| Metric | Description |
|---|---|
channel_patterns | Channel-specific activity and performance data over a specified period. By utilizing this metric, you can filter, limit, and order channel data to better understand how particular channels perform in terms of user engagement and activity. |
Parameters
filter: Allows you to filterchannel_patternsdata based on specific criteria. Currently, you can filter by channel names using operators likestartsWith,eq, etc.limit: Specify the number of results you want to return. No min or max values.orderBy: Define how the channel data should be ordered in the results by fields such as supported fields are:timestamp_value,count_messages,count_users,count_subscribers,count_users_with_messages, etc., in either ascending or descending order.
Top metrics
Metrics available on the /insights/top endpoint.
- Channels
| Metric | Description |
|---|---|
top_20_channels | Top 20 channels for the specified period, category, and date range. |
top_1000_channels | Top 1000 channels for the specified 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 specified 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 specified period, category, and date range. |
- Users
| Metric | Description |
|---|---|
top_20_users | Top 20 users for the specified period, category, and date range. |
top_1000_users | Top 1000 users for the specified period, category, and date range. |
Categories
Top metrics have a few categories that are either added in requests or returned in responses.
Requests
You can group the top metrics in each call by the following categories:
allby_chatsby_messagesby_subscribersby_users_with_chatsby_subscribed_channelsby_users_with_messages
Responses
Top metrics for a given hour (period=hourly) or day (period=daily) return the following categories in response:
| 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 | - | - |
count_subscribers | Number of subscribers for the channel. | Yes | Yes | - | - | - | - |
count_users_with_messaging | Number of unique users publishing messages within the channel. | Yes | Yes | - | - | - | - |
count_chat | Number of messages (that contain textual information) published. | Yes | Yes | Yes | Yes | - | - |
count_users_with_chat | Number of unique users publishing messages within the channel. | Yes | Yes | - | - | - | - |
count_channels_subscribed_to | Number of channels the user has subscribed to. | - | - | Yes | Yes | - | - |
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 | - | - |
avg_user_duration | On average how long users stay connected to the channel. | - | - | - | - | Yes | Yes |
user_duration_0_5_min | Number of users that stay connected to the channel for 0-5 minutes. | - | - | - | - | Yes | Yes |
user_duration_5_10_min | Number of users that stay connected to the channel for 5-10 minutes. | - | - | - | - | Yes | Yes |
user_duration_10_15_min | Number of users that stay connected to the channel for 10-15 minutes. | - | - | - | - | Yes | Yes |
user_duration_15_20_min | Number of users that stay connected to the channel for 15-20 minutes. | - | - | - | - | Yes | Yes |
user_duration_20_30_min | Number of users that stay connected to the channel for 20-30 minutes. | - | - | - | - | Yes | Yes |
user_duration_30_40_min | Number of users that stay connected to the channel for 30-40 minutes. | - | - | - | - | Yes | Yes |
user_duration_40_50_min | Number of users that stay connected to the channel for 40-50 minutes. | - | - | - | - | Yes | Yes |
user_duration_50_60_min | Number of users that stay connected to the channel for 50-60 minutes. | - | - | - | - | Yes | Yes |
For example, if you want to get metrics for the top 20 channels (top_20_channels) by the number of messages, choose the by_messages category.
Limitations
To manage the size of the response returned, there are limitations to how much data you can request in a single API call. This limit depends on:
- Type of metric (for example,
unique_channels) - Time period (
periodparameter, for example,hourly)
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.
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 | - | - |
top_1000_channels | Yes | Yes | - | - |
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 | - | - |
top_1000_users | Yes | Yes | - | - |
new_vs_recurring_users | - | Yes | Yes | Yes |
percent_unique_users_with_messages | Yes | Yes | Yes | Yes |
unique_users | Yes | Yes | Yes | Yes |
unique_users_by_country | Yes | Yes | - | - |
unique_users_combination | Yes | Yes | Yes | Yes |
- Messages
| Metric name | hourly | daily | weekly | monthly |
|---|---|---|---|---|
messages | Yes | Yes | Yes | Yes |
message_by_country | Yes | Yes | - | - |
top_10_message_types | Yes | Yes | - | - |
- User Duration & Devices
| Metric name | hourly | daily | weekly | monthly |
|---|---|---|---|---|
avg_user_duration | Yes | - | - | - |
unique_users_by_duration_timeframe | Yes | - | - | - |
top_20_channels_with_user_duration | Yes | - | - | - |
top_1000_channels_with_user_duration | Yes | - | - | - |
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 |