Rank pages, features, or track events against each other by aggregate usage over a date range. This is a cross-entity ranking tool, not a lookup or single-entity analytics tool: it cannot filter by entity name or ID, and its limited result set may omit a requested named entity even when that entity exists. Where entityUsage returns per-visitor rows for a single known entity, this tool returns one row per entity showing how an entire cohort (optionally scoped by a segment) uses every page, feature, or track event. Each row has entityId, entityName, appId, totalEvents, uniqueVisitors, and uniqueAccounts. totalEvents is the activity count for that entity: page VIEWS for pages, CLICKS for features, and event counts for track events - describe it with the term that matches the entity type. Pages and features also add totalErrorClickCount / totalRageClickCount / totalDeadClickCount; pages also add totalUTurnCount and avgTimePerVisitor. Track events have no frustration data. For features, pageId restricts the ranking to features associated with one known page. By default only entities with activity in the window are returned (sort ascending for least-used among used). Set includeUnused=true to also return entities with zero usage (zero-filled rows) - answering 'which entities get no use at all', or, when a segmentPipeline is supplied, 'which entities get no use from that segment'. COMPARISON MODE: supply compareToDateRange to rank entities by how their usage CHANGED between two periods - dateRange is the current/recent period, compareToDateRange is the earlier baseline. The headline metrics (totalEvents, uniqueVisitors, uniqueAccounts) are returned as current_<m>, prior_<m>, change_<m> (current - prior) and pctChange_<m>; the remaining metrics (frustration counts, avgTimePerVisitor) are returned as change_<m> only to keep rows compact. Sort by a change_ field (ascending = biggest drop-off, descending = biggest growth). This answers 'which pages dropped off the most' in one call - the ranking is done in the aggregation, so no per-entity cross-referencing is needed. includeUnused is ignored when comparing. USE FOR: Ranking or comparing entities of one type by usage - e.g. top pages by views, most-clicked features, most-clicked features associated with a page, least-used track events. With includeUnused=true, finding entirely unused entities (dead pages/features), optionally scoped to a segment. With compareToDateRange, ranking entities by period-over-period change - biggest drop-offs or biggest gainers. EXAMPLES: - Top 5 features by clicks last month - Which page had the most views in the last 30 days? - Which features have the most rage clicks this quarter? - Which features associated with page X were clicked most in the last 30 days? - Least-used track events over the last week - Which pages got no views at all in the last 30 days? - Which features were never used by visitors in segment X last month? - Which pages in product area X have zero activity from visitors in segment Y? - Which pages dropped off in usage the most this month versus last month? - Which features grew the most in the last 30 days compared to the prior 30 days? NOT FOR: Questions about the views, clicks, visitors, accounts, or other usage of one entity identified by name, such as 'How many people viewed Page X?'. A named entity missing from this ranked output is not evidence that it does not exist. WORKFLOW: For usage analytics about one named page, feature, or track event, call listCountables to resolve the name to an entity ID, then use entityUsage with that ID. Use aggregateEntityUsage only when the user asks to rank or compare multiple entities. RETURNS: - meta.dateRange: resolved startDate and endDate (YYYY-MM-DD); meta.compareToDateRange when comparing - rows: one per entity with entityId, entityName, appId, totalEvents (page views / feature clicks / track-event counts), uniqueVisitors, uniqueAccounts (pages/features also: totalErrorClickCount, totalRageClickCount, totalDeadClickCount; pages also: totalUTurnCount, avgTimePerVisitor). With includeUnused=true, unused entities appear with all-zero metrics. In comparison mode the headline metrics (totalEvents, uniqueVisitors, uniqueAccounts) are split into current_<m>, prior_<m>, change_<m> and pctChange_<m>, while the other metrics (frustration counts, avgTimePerVisitor) carry change_<m> only. Prefer change_ for mover/drop-off rankings (pctChange is noisy on small baselines and null when prior is 0).
Parameters
Time window. For a rolling window use type='relative' with lastNDays. For a fixed calendar range use type='absolute' with startDate and endDate in YYYY-MM-DD.
The kind of entity: 'page', 'feature', or 'trackEvent'. Required for an unscoped ranking, where there are no ids to carry the type. Ignored when productArea uses inline entities, because each entry names its own type. One of: `page`, `feature`, `trackEvent`.
Subscription ID that owns the data. Required for all queries.
Optional application ID to filter by. If omitted, includes all applications the user can access.
Optional baseline period for a period-over-period comparison. When supplied, dateRange is treated as the current/recent period and this as the earlier baseline; results are ranked by how each entity's usage changed (change = current - prior). Same shape as dateRange. A relative baseline (type='relative', lastNDays) is the N days IMMEDIATELY BEFORE dateRange - not the last N days from today - so type='relative' lastNDays=30 on both ranges means 'last 30 days vs the prior 30 days'. Use absolute dates for a fixed baseline such as the same month last year. Omit for a single-period ranking.
Whether to include unidentified visitors in the aggregates. Defaults to true. Default: `true`.
When true, additionally include entities with zero usage in the window. Use to find entirely unused entities - e.g. 'which pages got no views'. When a segmentPipeline is supplied, the segment scopes the usage measured, so a zero row means 'unused by that segment' regardless of other visitors. Defaults to false (only entities with activity). Ignored in comparison mode (compareToDateRange already returns every entity active in either period, including drop-offs to zero and arrivals from zero). With a single-type inline productArea it zero-fills the entities in that scope, which is the reliable way to ask which of a named set had no use at all - absence from ordinary rows can also mean the entity fell outside limit. Rejected with minEvents, and rejected when productArea spans more than one entityType. Default: `false`.
Maximum number of entity rows to return (1-200, default 10). Default: `10`.
Only count visitors whose own event total across the entities in scope reaches this number. The total is summed over the WHOLE scoped set, not per entity: with two inline ids a visitor with 1 event on A and 1 on B has a total of 2 and qualifies at minEvents=2, even though they clear it on neither entity alone. It is summed across entity types too when the bundle spans them, so one page VIEW plus one feature CLICK likewise totals 2 - that is what 'used this tier at least twice' asks for, but it is adding events of different kinds together, so say so when reporting a mixed-type threshold. The summary counts each qualifying visitor once; the rows then show how those visitors' events break down per entity. This counts events, not visits - several events can happen within one visit, so it does not measure returning or repeat visitors. It is always a threshold on visitors, never on accounts. Omit to count every active visitor. Not supported with includeUnused.
Optional page ID. Restricts the ranking to features associated with this page, so the scope has to be features only: valid with entityType='feature', or with an inline productArea whose only entry is a feature entry. Rejected when productArea spans more than one entityType.
Optional scope narrowing the query to a group of entities. Accepts, in one array: 1. Saved product area ids, e.g. ["pa-123"] or ["pa-1", "pa-2"] - use whenever the group already exists in Pendo. Members are unioned, so an entity in several is counted once. Ids are never names: resolve an area name with listProductAreas first. 2. The single token ["*"] - every saved product area. This means "in ANY product area" and therefore EXCLUDES entities belonging to none; it is NOT the same as omitting this argument, which spans everything whether it is in an area or not. 3. An inline list of entities grouped by type, e.g. [{"entityType":"feature","ids":["A","B"]},{"entityType":"page","ids":["C"]}]. Use this for a group that is not saved in Pendo - for example the pages and features making up a pricing tier - and pass the WHOLE group in ONE call. A group may span types, which is why the type travels with the ids. Give each entityType at most once with a non-empty ids list. Ids are never names: resolve names with the relevant entity listing tool first. An id that does not resolve is rejected rather than silently contributing zero. Saved area ids and inline entries cannot be mixed in the same array. Omit the argument entirely to leave the query unscoped.
Optional inline segment scope that yields visitorId rows. Accepted string shapes: 1. A saved segment ID string, embedded as {id: <segmentId>}. 2. A JSON string containing a full inline pipeline produced by the buildPendoSegment tool, you must not attempt to make this field up, only pass the result of the buildPendoSegment tool. You can pass the entire `pipeline` VERBATIM from the buildPendoSegment tool.
Field to sort results by. All entity types support 'totalEvents' (page views / feature clicks / track-event counts), 'uniqueVisitors', 'uniqueAccounts'. When productArea spans entity types only those three (or their comparison-mode prefixed forms) are accepted, since the rest are not reported for every type. Pages and features also support 'totalErrorClickCount', 'totalRageClickCount', 'totalDeadClickCount'. Pages also support 'totalUTurnCount' and 'avgTimePerVisitor'. Defaults to 'totalEvents'. In comparison mode (compareToDateRange supplied) sort by a prefixed column instead. The headline metrics (totalEvents, uniqueVisitors, uniqueAccounts) accept 'current_<field>', 'prior_<field>', 'change_<field>', or 'pctChange_<field>' (e.g. 'change_totalEvents', 'current_uniqueVisitors'); the other metrics (frustration counts, avgTimePerVisitor) accept 'change_<field>' only (e.g. 'change_totalRageClickCount'). Combine with sortOrder='asc' for biggest drop-offs or 'desc' for biggest gains. PREFER 'change_<field>' (absolute change) for 'biggest mover / drop-off / gainer' questions: it is self-normalising. Use 'pctChange_<field>' only when the user explicitly asks about percentage/rate of change, and be aware it is noisy on low-traffic entities (a 1->5 page reads as +400%) and is null when the prior period had zero activity (new entities). Default to 'change_totalEvents' when comparing.
'desc' (default, highest first - top/most used) or 'asc' (lowest first - least used). One of: `asc`, `desc`. Default: `desc`.
Optional short summary (under 20 words) of the Pendo task this call addresses, written in your own words, for usage analytics. Example: "Compare weekly active visitors for the Billing app".
.svg)
