Insights API metrics

This page lists the metrics, top-metric categories, and supported periods for the PubNub Insights API. The Insights API requires Insights Premium. The API returns all metrics in UTC.

The Insights API is part of the Admin API. The Admin API reference covers the request details: authentication with an Admin API key, endpoints, parameters, and response codes. Use this page to choose the metric names, category, and period you pass in a request.

Endpoint	Returns	Admin API reference
GET /v2/insights	General metrics for an account, app, or keyset	getData
GET /v2/insights/top	Top channels and users for an account, app, or keyset	getTopNData

Metric names are case-sensitive. If you request a metric for a period it doesn't support, the Admin API returns 400.

Insights general metrics

These metrics go in the metric[] parameter of GET /v2/insights.

Channel metrics

Metric	Description
unique_channels	Unique channels in the selected period
percent_unique_channels_with_messages	Percentage of channels with messages out of all unique channels
unique_channels_combination	Unique channels, unique channels with messages, and unique channels with message chats
channel_patterns	Channel activity and performance filtered, sorted, and limited by your parameters

User metrics

Metric	Description
unique_users	Unique users in the selected period
percent_unique_users_with_messages	Percentage of users with messages out of all unique users
unique_users_combination	Unique users, unique users with messages, and unique users with message chats
new_vs_recurring_users	New unique users and returning unique users compared with the preceding period
unique_users_by_country	Unique users per country in the selected period

Message metrics

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. Requires a JSON path in Messages Configuration if your payloads do not follow PubNub's message type conventions.

User duration and device metrics

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

Channel patterns options

The channel_patterns metric groups channels by name pattern. The filters, orderBy, and limit parameters of GET /v2/insights apply to channel_patterns results.

• filters supports the operators eq, neq, gt, lt, gte, lte, in, nin, startsWith, endsWith, and contains.
• orderBy supports the fields timestamp_value, count_messages, count_users, count_subscribers, and count_users_with_messages.
• limit sets the number of channel_patterns records returned.

Insights top metrics

These metrics go in the metric[] parameter of GET /v2/insights/top. Each request also needs a category. The filters parameter narrows results to specific channels or users and supports the operators eq, neq, gt, lt, gte, lte, in, nin, and startsWith.

Metric	Description
top_20_channels	Top 20 channels for the selected period and category
top_1000_channels	Top 1000 channels for the selected period and category
top_20_users	Top 20 users for the selected period and category
top_1000_users	Top 1000 users for the selected period and category
top_20_channels_with_user_duration	Top 20 channels with average user duration and user counts by duration bucket
top_1000_channels_with_user_duration	Top 1000 channels with average user duration and user counts by duration bucket

Insights top metric categories

The category parameter of GET /v2/insights/top sets how top channels and users are ranked.

Category	Description
all	All activity
by_messages	Ranked by message count
by_chats	Ranked by chat message count
by_subscribers	Ranked by subscriber count
by_users_with_messages	Ranked by users who published messages
by_users_with_chats	Ranked by users who published chat messages
by_subscribed_channels	Ranked by number of channels subscribed to (users only)

Supported periods for Insights metrics

Each metric supports only some values of the period parameter. These tables list which periods each metric accepts, including top metrics.

Channel metric periods

Metric	hourly	daily	weekly	monthly
unique_channels	Yes	Yes	Yes	Yes
percent_unique_channels_with_messages	Yes	Yes	Yes	Yes
unique_channels_combination	Yes	Yes	Yes	Yes
top_20_channels	Yes	Yes	No	No
top_1000_channels	Yes	Yes	No	No

User metric periods

Metric	hourly	daily	weekly	monthly
unique_users	Yes	Yes	Yes	Yes
percent_unique_users_with_messages	Yes	Yes	Yes	Yes
unique_users_combination	Yes	Yes	Yes	Yes
unique_users_by_country	Yes	Yes	No	No
new_vs_recurring_users	No	Yes	Yes	Yes
top_20_users	Yes	Yes	No	No
top_1000_users	Yes	Yes	No	No

Message metric periods

Metric	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 and device metric periods

Metric	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

Related pages

• Insights Introduction. Authenticate and call the Insights endpoints in the Admin API.
• PubNub Insights. See which plans include Insights Premium and what each dashboard shows.