query_stats
Run read-only analytics queries to retrieve aggregate totals, time series, or top-N breakdowns for a site's visitors, pages, sources, and goals.
Instructions
Run a read-only analytics query for one site: aggregate totals, a time series, or a top-N breakdown. Returns {"results":[{"dimensions":{...omitted for aggregates},"metrics":{...}}]}. All dates and time buckets are in the site's own timezone (see list_sites .timezone). The event:name breakdown lists custom events (data-statable-event); its events metric is the raw event count. The event:goal breakdown lists the site's configured goals with visitors (converters), events (conversions) and conversion_rate (percent). events/conversion_rate are breakdown-only (rejected on aggregate/time-series or a dimension that doesn't compute them). Units: visit_duration = average seconds per visit; bounce_rate = percent 0-100; views_per_visit = pageviews/visits ratio; visitors/pageviews/visits = counts.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| site | No | Numeric site_id (preferred, from list_sites) or a domain, e.g. example.com — scheme, www. and path are ignored when matching. If several sites share the domain the call fails and lists their site_ids. Omit for a single-site key. | |
| limit | No | Breakdown only. Default 100, max 1000. | |
| compare | No | "previous_period" (equal-length window before date_range) or a custom ["YYYY-MM-DD","YYYY-MM-DD"] pair. Adds a compare {value, change%} block: per-metric (aggregate), per-row (breakdown; not event:status_code/event:goal), or per-bucket (time-series). Time-series needs an equal-length range (else compare_length_mismatch). | |
| filters | No | ||
| metrics | Yes | ||
| date_range | Yes | Preset "7d" or "30d" (last N full days), "month" (current calendar month to date; the first bucket may land on the prior month's last day), "realtime" (last ~30 min — pair with the time:minute dimension), "Nd" for the last N days (1..90, e.g. "14d"), or a custom inclusive ["YYYY-MM-DD","YYYY-MM-DD"] pair (over 90 days use a custom pair). | |
| dimensions | No | Zero = aggregate; one time dimension (time, time:hour, time:day, time:week, time:month) = time series; one breakdown dimension = top-N. Besides the enum you may also pass a dynamic 'event:props:<key>' dimension to break a custom event down by one of its property values (metrics visitors + events) — it REQUIRES an 'event' filter to name the event, e.g. dimensions:['event:props:plan'] + filters:[{field:'event',operator:'is',values:['Signup']}]. |