Query PubNub Insights
insightsQuery PubNub Insights to retrieve aggregated analytics scoped to an account, app, or keyset. Get read-only metrics such as unique channels, users, messages, and top rankings.
Instructions
Queries PubNub Insights — read-only aggregated analytics scoped to an account, app, or keyset.
**Entity scoping:** Every query requires an entityType ('account', 'app', or 'keyset') and
an entityId. For 'account' and 'app', the entityId is the numeric ID. For 'keyset', the
entityId is the subscribe key (sub-c-...).
Two endpoints, picked automatically by metric name:
- /v2/insights → aggregated metrics (unique_channels, unique_users, messages, etc.)
- /v2/insights/top → ranked metrics (top_20_channels, top_20_users, top_10_message_types, etc.)
TOOL SELECTION GUIDE — Insights Claude Behavior:
1. Group-aware: Insights metrics are organized into 5 functional groups — Channels, Users,
Messages, User Behavior, Devices. When a user asks an analytic question, pick the right
group first and then the specific metric. See the how-to guides:
how_to(slug="how-to-get-insights-api-access"), channels, users, messages,
user-behavior-and-devices, filters.
2. Period rules (enforced at runtime):
- Duration metrics (avg_user_duration, unique_users_by_duration_timeframe,
top_*_channels_with_user_duration) → period=hourly ONLY.
- Top-N metrics (top_20_*, top_1000_*) → hourly or daily ONLY (no weekly/monthly).
- Country metrics → hourly or daily ONLY.
- new_vs_recurring_users → daily / weekly / monthly only (NOT hourly).
- All other metrics → all four periods supported.
3. Top metrics REQUIRE category. Without it, the call errors. Valid categories:
by_messages, by_chats, by_subscribers, by_users_with_messages,
by_users_with_chats, by_subscribed_channels, all.
4. Top-metric filtering uses `filters` (JSON), not `filter`. Use `filters` on
top_20_* / top_1000_* for thresholds (count_messages gt), allowlists (channel_name
in), and prefixes (uuid startsWith). Use `filter` only on channel_patterns.
5. UTC timestamps. fromDate and toDate are YYYY-MM-DD in UTC. Always frame the response
with the date range and timezone so the user has unambiguous context.
6. Top-N counts CANNOT be summed across periods. If the user asks for "top channels this
week" and you query with period=daily, return one ranking per day, not a weekly sum.
7. Default to period=daily for most queries. It supports the widest set of metrics and
gives a clean trend view. Use hourly only when intra-day granularity is needed or for
duration metrics.
8. Account must be on Insights Premium. Free plan has no API access. Pro existing
customers may need to upgrade from Standard to Premium. If a 403 comes back, surface
this as the likely cause.
9. The tool does not write or store anything. Insights is strictly read-only.Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| entityType | Yes | The type of entity to fetch metrics for: 'account', 'app', or 'keyset'. Use 'keyset' with a subscribe key as entityId for keyset-scoped queries. | |
| entityId | Yes | The ID of the entity. For entityType='account': numeric account ID. For 'app': numeric app ID. For 'keyset': the subscribe key (sub-c-...). | |
| metric | Yes | Insights metric to query. Top metrics (top_20_*, top_1000_*) route to /v2/insights/top automatically and require the `category` parameter. Duration metrics (avg_user_duration, unique_users_by_duration_timeframe, top_*_channels_with_user_duration) only support period=hourly. new_vs_recurring_users does NOT support period=hourly. See Period Restrictions table in the how-to guide for the full matrix. | |
| period | Yes | Time grain. Default to `daily` for most queries. Use `hourly` for intra-day or duration metrics. `weekly` and `monthly` are not supported by top-N metrics, country breakdowns, or some other categories. | |
| fromDate | Yes | Start date (inclusive) in YYYY-MM-DD format, UTC. | |
| toDate | Yes | End date (inclusive) in YYYY-MM-DD format, UTC. | |
| category | No | Required ONLY for top metrics (top_20_*, top_1000_*). Picks the ranking dimension. by_subscribers, by_users_with_messages, by_users_with_chats apply to channel rankings only. by_subscribed_channels applies to user rankings only. Use `all` for combined results. | |
| filter | No | Filter expression for metric=channel_patterns only (`startsWith:group.` or `eq:lobby`). Do not use for top metrics — use `filters` instead. | |
| filters | No | JSON object for top metrics on /v2/insights/top. Top-level key must match `metric` (e.g. top_1000_channels). Value is an array of {field, operator, value} conditions combined with AND. Operators: eq, neq, gt, lt, gte, lte, in, nin, startsWith. See how_to(slug="how-to-query-insights-filters"). | |
| orderBy | No | Sort field and direction (e.g. `count_messages:desc`). Optional — most metrics default to a sensible ordering. | |
| limit | No | Number of results to return. Optional — top metrics already cap at 20 or 1000 by name. |