Discover the event-name vocabulary in a date window (schema discovery). Scans ALL Vexo events in [start_date, end_date] and returns the top 50 event names by frequency. Use this FIRST when you don't know which event names exist. event_name = metadata.name if present, else the event's top-level "type".

Inputs: start_date: ISO date "YYYY-MM-DD" (or full ISO datetime), e.g. "2026-06-01". end_date: ISO date, e.g. "2026-06-07". MUST be <= 31 days after start_date (Vexo caps a single range at ~31 days). Date-only end is inclusive.

Returns: { window:{start,end,days}, total_events, distinct_event_names, event_names:[{event_name, count}, ... up to 50, desc] }. On failure: { error }.

Aggregate event counts over a date range, optionally grouped by a dimension. The workhorse for cohort comparison. Ranges > 31 days are split & merged automatically (deduped by event id).

A "dimension" is any top-level field (deviceId, country, deviceSystemName, appVersion, route, sessionId, deviceModel, city, type) OR any metadata key (e.g. "worker_id", "user_id").

Inputs: start_date, end_date: ISO dates (end inclusive of the day). group_by: OPTIONAL dimension to group by, e.g. "worker_id". If omitted, the server's configured group key is used; if none, results are totaled by event_name only. filter_values: OPTIONAL list restricting group_by to these values, e.g. ["54","111","2716"] to compare a specific cohort. Max 200. filters: OPTIONAL extra key/value constraints, e.g. {"deviceSystemName":"iOS"}. event_names: OPTIONAL list to restrict which events are counted.

Returns: { window, group_by, rows:[{group?, event_name, count}], truncated, total_count? }. Sorted by group then count desc. Groups/events with zero matches are absent. On failure: { error }.

Per-day timeline of specific events. Use to detect cutover dates — the day a group STOPS (or starts) firing an event. event_names is REQUIRED to bound output. Counts are bucketed by calendar day (UTC). Ranges > 31 days auto-split.

Inputs: event_names: REQUIRED list, e.g. ["worker_shift_feed_viewed","screen_view"]. start_date, end_date: ISO dates (end inclusive). group_by: OPTIONAL dimension, e.g. "worker_id" (defaults to server group key). filter_values: OPTIONAL list restricting group_by to these values. Max 200. filters: OPTIONAL extra key/value constraints. granularity: only "day" is supported.

Returns: { window, granularity, group_by, rows:[{group?, date, event_name, count}], truncated, total_count? }. Sorted by group, date, event_name. Days with no events are absent (a gap == no activity). On failure: { error }.

Summarize the most recent app sessions, grouped by an entity. Use to tell a "bailed out" session (short, few screens) apart from an "event-poor" session (normal length but missing data events).

By default scans the configured lookback window (default 30 days) ending now; pass start_date/end_date to override. Groups events by sessionId, then returns the N most recent sessions per group value (most recent first).

Inputs: group_by: OPTIONAL entity dimension (defaults to server group key, else "deviceId"), e.g. "worker_id". filter_values: OPTIONAL list restricting group_by to these values. Max 200. filters: OPTIONAL extra key/value constraints. n_sessions_per_group: default 20, max 50. start_date, end_date: OPTIONAL ISO dates to override the lookback window.

Returns: { window, group_by, rows:[{group?, session_id, start, end, duration_s, screen_count, event_count, last_screen}], truncated, total_count? }. screen_count = # of screen_view events. On failure: { error }.

Forensic dive into one entity's most recent raw events (newest first). Use after the aggregate tools point you at a specific entity and you need to read the actual event stream — names, screens, sessions, payloads.

Scans the configured lookback window (default 30 days) unless start_date/ end_date are given. Identify the entity with the "filters" selector.

Inputs: filters: REQUIRED key/value selector identifying the entity, e.g. {"worker_id":"54"} or {"deviceId":"abc-123"}. n: number of most recent events. Default 10, max 50. start_date, end_date: OPTIONAL ISO dates to override the lookback window.

Returns: { filters, window, rows:[{timestamp, event_name, screen, session_id, metadata}], truncated, total_count? }. On failure: { error }.

High-level breakdown of activity in a date window. Good first call to understand an app's traffic. Scans all events in [start_date, end_date] (<= 31 days) and returns totals plus top breakdowns.

Inputs: start_date, end_date (ISO dates, end inclusive, <=31 days apart).

Returns: { window, total_events, unique_sessions, unique_devices, by_event_type:[{value,count}], top_routes:[...], by_os:[...], top_devices:[...], by_country:[...], by_app_version:[...] } (each top list capped at 15). On failure: { error }.