Insights API
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. |
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. |
- 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 |
|---|---|---|---|---|---|
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 |
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) - Date range (
fromDateandtoDateparameters, for example,2023-10-02and2023-10-09if you want data for 7 days)
Date range restrictions with period
When you request metrics data from Insights API, keep these limitations in mind.
| Period | Restrictions | Example |
|---|---|---|
hourly | You can request a maximum 1 day in one API call and only till the preceding 10 hours. | If the current date is 2023-11-28 (22:10:00 UTC), you can request metrics for the hourly period from 2023-11-27 (12:00:00 UTC) till 2023-11-28 (12:00:00 UTC). |
daily | You can request maximum 7 days in one API call and only till the preceding/previous day. | If the current date is 2023-11-28 (22:10:00 UTC), you can request metrics for the daily period from 2023-11-21 (00:00:00 UTC) till 2023-11-27 (end of day). |
weekly | You can request maximum 8 weeks in one API call and only till the previous week (only for complete weeks, with weeks starting on Sunday). | If the current date is 2023-11-28 (22:10:00 UTC), you can request metrics for the weekly period from Sun 2023-10-01 (00:00:00 UTC) till Sat 2023-11-25 (end of day). |
monthly | You can request maximum 3 months in one API call and only for the preceding month on the first day of this month. | If the current date is 2023-11-28 (22:10:00 UTC), you can request metrics for the monthly period from Sun 2023-08-01 (00:00:00 UTC) till Sun 2023-10-31 (end of day). |
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 | - | - |