query
Run a flexible ad-hoc analytics query with custom metrics, filters, grouping, date ranges, and privacy-first customer email lookup. This is the most powerful endpoint — use it when other tools don't answer the question.
Examples of questions this tool answers:
"How many signups from Germany this week?" → filters: [{field:"event",op:"eq",value:"signup"},{field:"country",op:"eq",value:"DE"}]
"Which events contain 'page' in the name?" → filters: [{field:"event",op:"contains",value:"page"}], group_by: ["event"]
"Daily unique users for the last 30 days" → metrics: ["unique_users"], group_by: ["date"], date_from: "30d"
"Events per country" → group_by: ["country"]
"Signups by path and day" → metrics: ["event_count"], filters: [{field:"event",op:"eq",value:"signup"}], group_by: ["date", "properties.path"]
"p75 of LCP" → use the web_vitals tool (p75 is the headline). For an ad-hoc percentile on hosted, metrics: ["p75"], property: "cwv_lcp", filters: [{field:"event",op:"eq",value:"page_view"}]
"Revenue collected" → metrics: ["sum"], property: "revenue"
Filter operators: eq, neq, gt, lt, gte, lte, contains Filterable fields: event, user_id, date, country, session_id, timestamp, and any properties.* field (e.g. properties.path) For customer-specific reads, use the top-level email input instead of hashing locally. Raw email is sent only in the authenticated HTTPS POST body; the server matches via a project-scoped HMAC index and does not store raw email in event rows or profile traits. Built-in fields are a closed list. Event properties such as referrer, utm_source, path, browser, and hostname must be queried as properties.referrer, properties.utm_source, properties.path, properties.browser, and properties.hostname. Invalid filter fields fail loudly and return /properties-style guidance instead of being silently ignored. Group by: event, date, user_id, session_id, country, and at most one properties.. The key matches ^[A-Za-z0-9_]{1,128}$, the same rule as property filters. Result rows use the column name properties.. A null or missing property value is grouped as null. Two properties.* entries return 400 INVALID_GROUP_BY. Metrics: event_count, unique_users, session_count, bounce_rate, avg_duration, sum, avg, p50, p75, p95 Numeric property metrics sum, avg, p50, p75, and p95 are Pro, with the same gating as this query. A free account gets 403 PRO_REQUIRED and that rejection is not metered. property is the event property key and is required when any of those metrics is requested. On hosted, cwv_lcp, cwv_inp, cwv_cls, cwv_fcp, and cwv_ttfb are properties on page_view when the tracker snippet includes data-track-vitals="true". Use the web_vitals tool for the p75 headline, ratings, and good/needs-improvement/poor shares. For an ad-hoc query, filter event to page_view. property must match ^[A-Za-z0-9_]+$ and be at most 128 characters. Missing property is 400 MISSING_FIELDS. An invalid key is 400 INVALID_PROPERTY_KEY. Only JSON numbers are aggregated. Numeric strings, booleans, nulls, and missing keys are skipped. Each row includes the requested metrics plus n (numeric values used) and skipped whenever an aggregation metric is requested. Percentiles are nearest-rank: percentile_method is nearest_rank when a percentile is requested and null for sum or avg only. avg is rounded to 6 decimal places. order_by may be a requested aggregate, for example p75. Count modes: raw, session_then_user. The default for event_count is session_then_user for activation-safe counting: session-backed rows count by session, no-session rows fall back to user only when that user has no session-backed row in the same group, and fully anonymous rows fall back to event id. count_mode is ignored when event_count is not requested.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"project": "<project>"
},
"name": "query"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| No | Filter by server-side scoped HMAC email lookup. Raw email is sent only in the authenticated HTTPS POST body and is not stored in event rows or profile traits. | ||
| limit | No | Max results (default 100, max 1000) | |
| order | No | Sort direction | desc |
| date_to | No | End date (ISO 8601). Defaults to today. | |
| filters | No | Filters to apply | |
| metrics | No | Metrics to compute. sum, avg, p50, p75, and p95 require property | |
| project | Yes | Project name | |
| group_by | No | Fields to group by. Each item is event, date, user_id, session_id, country, or properties.<key>. The key matches ^[A-Za-z0-9_]{1,128}$. At most one properties.<key>. The result column is properties.<key>, and null or missing values group as null. | |
| order_by | No | Field to sort by. Aggregate metrics such as p75 are allowed when requested | |
| property | No | Event property key to aggregate, for example cwv_lcp or revenue. Required when metrics include sum, avg, p50, p75, or p95. Must match ^[A-Za-z0-9_]+$ and be at most 128 characters | |
| date_from | No | Start date (ISO 8601 or Nd shorthand like '30d'). Defaults to 7 days ago. | |
| count_mode | No | How event_count is aggregated. Default for event_count: session_then_user. Session-backed rows count by session, no-session rows fall back to user only when that user has no session-backed row in the same group, and fully anonymous rows fall back to event id. Ignored for queries without event_count. Use raw for ingestion/debugging counts. |