Event query
run_insights_queryRead-onlyIdempotent
Count events or sum/average a numeric detail by day/week/month/hour, filtered, split by a property (top 10; table 100) or as 1-4 series (A-D); compare_previous adds the change vs the prior period. Counts events, not visitors. Use summary_total or a series' total. Non-numbers skipped: say if left_out set. Buckets marked partial cover only part of their week/month/year (see covers_from/covers_to) or contain today: never read a partial bucket as a drop. By hour: the current hour is incomplete, later hours read 0. Dates are the project's calendar days, YYYY-MM-DD (timezone: get_project); timestamps are UTC. Omit from/to for the last 28 complete days, ending yesterday. A period marked starts_before_data begins before the project has data (see data_from): those days read as zero, not as a quiet period. Quote counts with every percentage; a big change on a small count is noise, not a finding.
Tool call template
This tool declares no required parameters. Add optional parameters from the input schema as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {},
"name": "run_insights_query"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | Last day, YYYY-MM-DD in the project's timezone, inclusive. Default: yesterday, the last complete day. | |
| from | No | First day, YYYY-MM-DD in the project's timezone, inclusive. Default: 27 days before 'to'. | |
| label | No | Optional short name of the query's one series as a chart shows it, at most 60 characters (e.g. Revenue). With series, give each series its label instead. | |
| limit | No | With a breakdown: how many top values, 1-10 (default 10), up to 100 with visualization table. | |
| series | No | Instead of measure, measure_property, event_type, filters and label (not together): 1 to 4 series compared in one chart on the same buckets, keyed A, B, C, D in order, each with its own measure, measure_property, event_type, filters and label. Each series counts exactly what the same query alone would. Several series take no breakdown; their totals are in result.series, and summary_total is then null. | |
| filters | No | Filters. Every item must hold (AND); an item is one filter (property, operator, value) or an any group of filters of which at least one must hold (OR), e.g. [{property: data_track, operator: equals, value: checkout}, {any: [{property: page_path, operator: equals, value: /pricing}, {property: page_path, operator: equals, value: /plans}]}]. | |
| measure | No | events (default): count the matching events. sum or average: add up or average measure_property, per event, over the matching events whose value is a number: a numeric event detail, or a page view's scroll_depth (average only) or time_on_page_seconds. Values that are not numbers are left out and counted in non_numeric_events; an average bucket with no numbers is null, not 0. | |
| project | No | Project ID, from list_projects. Required when this connection covers more than one project; may be left out when it covers one (and with an API key, which belongs to one project). | |
| sort_by | No | With a breakdown: the series (A, B, C or D) the rows are ordered by, highest first. In a table the rows are every value any series has among its own top limit, so a value only one series has is a row (0, or null for a sum or average, in the others). Default A. | |
| group_by | No | Bucket size: day (default), week, month or hour. hour needs a range of at most 31 days, from and to both included; its points are the hours of the project's timezone (23 or 25 on a day the clocks change), each with date (its day) and start (the hour with the project's UTC offset). | |
| breakdown | No | Split by a property (same names as filters, or event_type; automated splits into true and false; scroll_depth and time_on_page_seconds cannot be a breakdown); query.utm_source, query.utm_medium and query.ref group lower-cased. Only the top 10 groups are returned: the most events, the largest sums, or for average the groups with the most numbers. For events and sum use summary_total as the denominator; for average summary_total is the average over all events with a number, each event once. | |
| event_type | No | Only this event type: pageview, click, form_submit, custom, dead_click, rage_click, error_click or slow_click (friction signals: a click after which nothing happened, a burst of rapid clicks, a click followed by an uncaught error, a click that took long to show any effect; never part of a feature). Omit for all. | |
| visualization | No | Only table changes the answer: with a breakdown, several series may then have one, as rows (result.table: one row per detail value or other breakdown value, a column per series), and limit may be up to 100. Omit otherwise. | |
| compare_previous | No | Also return each series' value over the previous period (the equally long run of days right before from..to) and the change, in comparison (on the result, or on each of result.series): what a single-value widget (visualization number) shows. No breakdown with it. When the previous period starts before the project's data there is no change: say so instead of comparing. | |
| measure_property | No | For sum and average only, and then required: the event detail to read, attrs.KEY (e.g. attrs.order_value for track('Purchase', { order_value: 34.5 })), or scroll_depth (average only) or time_on_page_seconds: a page view's scroll depth in percent (0-100) and its active seconds (0-1800); only page views with a value take part (null means no value arrived, never 0), and a page_path filter narrows it to one page. list_property_keys lists the keys; filter to the event that carries a detail (e.g. data_track equals Purchase). A number is plain decimal text such as 34.5 or -2: '34,50', '€34' and '1e3' are not numbers. |