Pug

GetEventExplorer returns a paginated, filterable list of events across all users in a project. Does not resolve aliases. Traffic tagged as a bot at ingest is excluded unless include_bots is true.

GetActivityFeed returns a paginated, filterable list of events for a user profile. Resolves profile aliases so merged anonymous events are included. Traffic tagged as a bot at ingest is excluded unless include_bots is true.

GetFilterSchema returns event names, property keys, and profile property keys for filter UIs. The filter-schema concept is service-agnostic; both shared.activity and shared.insights expose the same shape via common.v1.

GetActivityHeatmap returns per-day event counts for a user profile over a time window. Defaults to the last 60 days when no time_range is provided. Traffic tagged as a bot at ingest is excluded unless include_bots is true.

GetPropertyValues returns distinct values for a given property key.

Get returns one dashboard: its time window, its tiles and its update_time. Each tile has its id, its name, its spec (insight tiles) or markdown, its chart and its position on the 12-column grid. Pass update_time to upsert_dashboard when you edit the dashboard.

GetDeletionRequest returns the status of an erasure request so a controller can prove fulfilment within the statutory window (the DSAR audit trail).

GetFilterSchema lists the event kinds and the property keys/types available to filter and break down by. Call it before query_insights so that filters and breakdowns reference keys that actually exist in this project.

The filter-schema concept is service-agnostic; both shared.insights and shared.activity expose the same shape via common.v1.

GetPropertyValues lists the observed values of an event or user property (e.g. the countries seen for "$country") so filters and breakdowns can be populated with real values before running query_insights.

Get returns a single user profile by its pug profile id, including identity properties and an activity summary. A claimed anonymous id is redirected to its canonical profile. Traffic tagged as a bot at ingest is excluded from the activity summary unless include_bots is true.

GetByExternalId returns a single user profile looked up by the external_id your application assigned to its end user, rather than by pug's internal profile id. Traffic tagged as a bot at ingest is excluded from the activity summary unless include_bots is true.

GetProfileSessions returns a paginated list of one user profile's sessions, newest first unless sort says otherwise. Requires that user's distinct_id (the pug profile id a profile lookup gives you). Sessions are aggregated server-side — one row per session with its start, end, event count and device context — so a profile with more events than any one page can hold still lists every session, with exact durations and counts. Resolves profile aliases so merged anonymous events are included. To page, send the previous response's next_page_token back as page_token; an empty next_page_token means there are no more pages. A token is only valid for the sort it was issued under — to change sort, start again with no page_token. sort defaults to PROFILE_SESSION_SORT_STARTED_AT and every sort is descending, so DURATION lists the longest sessions first and EVENT_COUNT the busiest. Traffic tagged as a bot at ingest is excluded unless include_bots is true, and the judgement is per session: a session with any tagged event is omitted whole rather than returned with only its untagged events.

GetProfileStats returns aggregate statistics, device/browser/location context from the latest event, per-day heatmap data (last 60 days), and profile properties for a profile. Resolves aliases so merged anonymous events are included. Traffic tagged as a bot at ingest is excluded unless include_bots is true, so a profile whose events are all bot-tagged omits stats entirely and returns no heatmap days — not a NotFound, and profile properties are still returned.

List returns the project's dashboards: each one's name, description, tile count, whether sharing is on, and when it last changed. Call get_dashboard for one dashboard's tiles.

List returns the projects you can read, each with the org it belongs to. Every other tool reads one project and takes its id as project_id, so call this first. When a question doesn't say which project and more than one could fit, ask. A connection made by signing in reads the projects of the orgs its person belonged to when they connected; an API key reads its own project only.

Query runs a product-analytics insight over the project's events and returns the computed result. A single call covers every insight type — trends, segmentation, funnel, retention, user flow (Sankey), top-K and map (a metric per country, returned as top_k rows keyed by ISO alpha-2) — chosen by the InsightQuerySpec (its insight_type, events, breakdowns and filters, among others). Map, user flow, top-K and session each carry their own sub-message (spec.map / spec.user_flow / spec.top_k / spec.session) and take no events or breakdowns; a map's country dimension is implicit, so spec.map may be empty. The request also carries the time range and granularity, and it is the right tool for any project-wide or over-time question; per-granularity range caps apply. Traffic tagged as a bot at ingest is excluded unless spec.include_bots is true. Discover valid event kinds and property keys with the get_insights_filter_schema tool first.

Upsert creates a dashboard or edits one. It returns the dashboard's link, if the server has one, which you give to the person, and the ids of the tiles you sent, in order. To create, leave id empty and give a name and tiles. To edit, pass the dashboard's id and its update_time, from get_dashboard or your last upsert_dashboard. If someone changed the dashboard since, the call fails; read it again. A tile without an id is added and needs exactly one of spec and markdown. Tile names must differ on a dashboard, ignoring case. To change a tile, send its id and only the fields that change; spec and position are replaced whole. A tile stays insight or markdown; to switch, add a new tile and remove the old one. Tiles you leave out stay as they are. To remove a tile, list its id in remove, and only when the person asked for it. Every insight tile shows the dashboard's default_time_range and default_granularity (the last 30 days by day when unset), so work out each one with query_insights over that window first. Dashboards can't show segmentation insights or session metrics. chart applies to trends and top K only. Positions use a 12-column grid: x is 0 to 10, w is 2 to 12, and x + w is at most 12. y and h count rows of about 18px; h is at least 15 for an insight tile and 9 for a KPI or markdown tile. A tile you place can't overlap another; leave position out to put a new tile below the others. Markdown can't contain images. A dashboard with sharing on can't be edited.