Run a traffic or event report
fathom_get_aggregationFathom's custom report (the dashboard's numbers): aggregate pageviews or one event over a date range, optionally grouped by date and/or fields and filtered. Pageviews: aggregates visits (unique site visits), uniques (unique page visits), pageviews, avg_duration (seconds), bounce_rate. Events (entity event + event_name): conversions, unique_conversions, value (in cents). Examples: top pages = field_grouping [pathname], sort_by pageviews:desc; traffic sources = [referrer_source] or [referrer_hostname]; AI referrals = [ai_source]; daily trend = date_grouping day. All numbers come back as strings. Dates are in the site's timezone; hour grouping only for ranges up to 7 days. Grouped reports return at most 500 rows unless limit is set (max 1000, no paging), so narrow with filters or dates. Data before March 2021 cannot be grouped/filtered. GET /aggregations.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Row cap, 1-1000 (default 500 when grouping by fields). | |
| entity | Yes | pageview = site traffic; event = one event's conversions (needs event_name). | |
| date_to | No | End, YYYY-MM-DD (end of day) or "YYYY-MM-DD HH:MM:SS", in the site's timezone. Default: now. | |
| filters | No | Filters, all applied (AND). Example: [{"property":"country_code","operator":"is","value":"GB"}]. | |
| site_id | Yes | The site id, the same string as in the tracking code (e.g. CDBUGS). fathom_list_sites lists them. | |
| sort_by | No | "<field>:asc|desc" with a field from aggregates or field_grouping (or timestamp with date_grouping), e.g. pageviews:desc. | |
| date_from | No | Start, YYYY-MM-DD (start of day) or "YYYY-MM-DD HH:MM:SS", in the site's timezone. Default: the first recorded data. | |
| aggregates | Yes | Metrics. pageview: visits, uniques, pageviews, avg_duration, bounce_rate. event: conversions, unique_conversions, value. | |
| event_name | No | For entity event: the event's name, as listed by fathom_list_events. | |
| date_grouping | No | Group by time (omit for one total). hour only for ranges up to 7 days. | |
| field_grouping | No | Group by these fields, e.g. [pathname] or [referrer_source, utm_campaign]. |