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:

UTC timezone for metrics

PubNub Insights API returns all metrics in the UTC timezone.

Metrics

Metrics available on the /insights endpoint.

  • Channels
MetricDescription
percent_unique_channels_with_messagesThe percentage of channels with messages out of all unique channels in the specified period and date range.
unique_channelsNumber of unique channels for the specified period and date range.
unique_channels_combinationUnique 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
MetricDescription
new_vs_recurring_usersNumber of new unique users and returning unique users (compared with the preceding period) for the specified period and date range.
percent_unique_users_with_messagesThe percentage of users with messages out of all unique users in the specified period and date range.
unique_usersNumber of unique users for the specified period and date range.
unique_users_by_countryNumber of unique users across all channels per country for the specified period and date range.
unique_users_combinationUnique 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
MetricDescription
messagesNumber of messages published across all channels for the specified period and date range.
message_by_countryTotal 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_typesTop 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
MetricDescription
avg_user_durationData 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_timeframeData 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_typeNumber of Publish calls by device type for a subscribe key in the specified period.
subscribers_by_device_typeNumber of Subscribe calls by device type for a subscribe key in the specified period.
unique_users_by_device_typeNumber of unique users by device type for a subscribe key in the specified period.

Top metrics

Metrics available on the /insights/top endpoint.

  • Channels
MetricDescription
top_20_channelsTop 20 channels for the specified period, category, and date range.
top_1000_channelsTop 1000 channels for the specified period, category, and date range.
top_20_channels_with_user_durationTop 20 channels with average user duration & number of users by duration for the specified period, category, and date range.
top_1000_channels_with_user_durationTop 1000 channels with average user duration & number of users by duration for the specified period, category, and date range.
  • Users
MetricDescription
top_20_usersTop 20 users for the specified period, category, and date range.
top_1000_usersTop 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:

  • all
  • by_chats
  • by_messages
  • by_subscribers
  • by_users_with_chats
  • by_subscribed_channels
  • by_users_with_messages

Responses

Top metrics for a given hour (period=hourly) or day (period=daily) return the following categories in response:

Returned categoryDescriptiontop_20_channelstop_1000_channelstop_20_userstop_1000_userstop_20_channels_with_user_durationtop_1000_channels_with_user_duration
count_messagesNumber of messages published.YesYesYesYes--
count_subscribersNumber of subscribers for the channel.YesYes----
count_users_with_messagingNumber of unique users publishing messages within the channel.YesYes----
count_chatNumber of messages (that contain textual information) published.YesYesYesYes--
count_users_with_chatNumber of unique users publishing messages within the channel.YesYes----
count_channels_subscribed_toNumber of channels the user has subscribed to.--YesYes--
timestamp_valueTimestamp of the hour or day for which the top 20 / 1000 channels / users have been requested. This timestamp is in UTC.YesYesYesYes--
avg_user_durationOn average how long users stay connected to the channel.----YesYes
user_duration_0_5_minNumber of users that stay connected to the channel for 0-5 minutes.----YesYes
user_duration_5_10_minNumber of users that stay connected to the channel for 5-10 minutes.----YesYes
user_duration_10_15_minNumber of users that stay connected to the channel for 10-15 minutes.----YesYes
user_duration_15_20_minNumber of users that stay connected to the channel for 15-20 minutes.----YesYes
user_duration_20_30_minNumber of users that stay connected to the channel for 20-30 minutes.----YesYes
user_duration_30_40_minNumber of users that stay connected to the channel for 30-40 minutes.----YesYes
user_duration_40_50_minNumber of users that stay connected to the channel for 40-50 minutes.----YesYes
user_duration_50_60_minNumber of users that stay connected to the channel for 50-60 minutes.----YesYes

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 (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_channelsYesYes--
top_1000_channelsYesYes--
percent_unique_channels_with_messagesYesYesYesYes
unique_channelsYesYesYesYes
unique_channels_combinationYesYesYesYes
  • Users
Metric namehourlydailyweeklymonthly
top_20_usersYesYes--
top_1000_usersYesYes--
new_vs_recurring_users-YesYesYes
percent_unique_users_with_messagesYesYesYesYes
unique_usersYesYesYesYes
unique_users_by_countryYesYes--
unique_users_combinationYesYesYesYes
  • Messages
Metric namehourlydailyweeklymonthly
messagesYesYesYesYes
message_by_countryYesYes--
top_10_message_typesYesYes--
  • User Duration & Devices
Metric namehourlydailyweeklymonthly
avg_user_durationYes---
unique_users_by_duration_timeframeYes---
top_20_channels_with_user_durationYes---
top_1000_channels_with_user_durationYes---
publishes_by_device_typeYesYesYesYes
subscribers_by_device_typeYesYesYesYes
unique_users_by_device_typeYesYesYesYes
Last updated on