Insights API Overview

Availability

PubNub Insights metrics are available through API only in Insights Premium.

You can view Insights in the Admin Portal. If you use Premium, you can also get app metrics with the Insights API.

Insights metrics​

You can request two sets of Insights metrics:

UTC timezone for metrics

PubNub Insights API returns all metrics in the UTC timezone.

Metrics​

The /insights endpoint returns these metrics.

  • Channels
MetricDescription
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). Message chats are text messages.
  • Users
MetricDescription
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). Message chats are text messages.
  • Messages
MetricDescription
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
MetricDescription
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
MetricDescription
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 endpoint.

  • Channels
MetricDescription
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
MetricDescription
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 categoryDescriptiontop_20_channelstop_1000_channelstop_20_userstop_1000_userstop_20_channels_with_user_durationtop_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)
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 namehourlydailyweeklymonthly
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 namehourlydailyweeklymonthly
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 namehourlydailyweeklymonthly
messages
Yes
Yes
Yes
Yes
message_by_country
Yes
Yes
No
No
top_10_message_types
Yes
Yes
No
No
  • User Duration & Devices
Metric namehourlydailyweeklymonthly
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
Last updated on
On this page