traffic.breakdown
Break down web traffic by dimensions like page paths, referrers, geography, devices, or UTM tags. Aggregate visitors and pageviews, filter by criteria, and sort by volume.
Instructions
Aggregate visitors and pageviews grouped by a single dimension. The dimension parameter chooses what to group by — page paths, traffic sources, geography, devices, or marketing attribution. Results are sorted by visitors descending and capped by limit (default 10, max 50). Some dimensions return additional joined columns: dimension="referrer_host" includes the channel for each referrer; dimension="city" includes the ISO country code. All other dimensions return only {name, pageviews, visitors}. Filters narrow the set before aggregation.
Examples:
"top pages last week" → dimension="pathname", period="7d"
"who is sending traffic" → dimension="referrer_host"
"mobile vs desktop split" → dimension="device_type"
"best UTM campaigns" → dimension="utm_campaign"
"top cities in Germany" → dimension="city", country="DE"
"browser version distribution" → dimension="browser_version"
Limitations: aggregates pageview events only — for custom event breakdowns use events.list with group_by. The name column is the raw stored value (lowercase ISO codes for country, exact pathname strings including trailing slash). Per-page time-on-page or bounce rate is not included here — use pages.engagement for that.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | No | Target project ID (e.g. "proj_abc123"). Required when the credential has access to multiple projects. If omitted and only one project is accessible, that project is used automatically. Call `projects.list` to discover available project IDs. | |
| dimension | Yes | What to group by. Page paths: "pathname", "entry_page", "exit_page". Traffic sources: "referrer_host" (returns channel too), "channel", "utm_source", "utm_medium", "utm_campaign", "utm_content", "utm_term". Geography: "country", "region", "city" (returns country too). Devices: "device_type", "browser", "browser_version", "os", "os_version". | |
| period | No | Time period. Use "today", "yesterday", "7d", "30d", "90d", or a custom range as "YYYY-MM-DD:YYYY-MM-DD" (e.g. "2026-01-01:2026-03-31"). Defaults to "30d". | |
| limit | No | Max rows to return (1-50). Defaults to 10. | |
| pathname | No | Filter to a specific page path (e.g. "/pricing", "/blog/my-post"). Must start with /. | |
| utm_source | No | Filter by UTM source (e.g. "google", "twitter", "newsletter"). Case-sensitive, must match the value in the tracking URL. | |
| utm_medium | No | Filter by UTM medium (e.g. "cpc", "email", "social"). Case-sensitive. | |
| utm_campaign | No | Filter by UTM campaign name (e.g. "spring-launch", "product-hunt"). Case-sensitive. | |
| utm_content | No | Filter by UTM content (e.g. "hero-cta", "sidebar-banner"). Case-sensitive. | |
| utm_term | No | Filter by UTM term (e.g. "running+shoes"). Case-sensitive. | |
| referrer_host | No | Filter by referrer hostname (e.g. "news.ycombinator.com", "twitter.com", "github.com"). Use this to see what traffic from a specific source did. Must match the value returned by `traffic.breakdown(dimension="referrer_host")` exactly (lowercase, no protocol or path). | |
| country | No | ISO 3166-1 alpha-2 country code, uppercase (e.g. "US", "GB", "DE", "NL", "JP"). Filter results to visitors from this country. | |
| region | No | Administrative region inside a country (e.g. "California", "Bavaria"). Case-sensitive; must match the stored region exactly. Use traffic.breakdown(dimension="region") to discover values. | |
| city | No | City name (e.g. "San Francisco", "London"). Case-sensitive; must match the stored value. Use traffic.breakdown(dimension="city") to discover values. | |
| device_type | No | Device category. One of: "desktop", "mobile", "tablet". | |
| browser | No | Browser family (e.g. "Chrome", "Safari", "Firefox"). Use traffic.breakdown(dimension="browser") to discover the exact stored values. | |
| browser_version | No | Browser version string (e.g. "120.0"). Case-sensitive. | |
| os | No | Operating system family (e.g. "macOS", "iOS", "Windows", "Android"). Use traffic.breakdown(dimension="os") to discover stored values. | |
| os_version | No | OS version string (e.g. "14.2"). Case-sensitive. | |
| channel | No | Traffic channel. One of: "direct", "organic_search", "organic_social", "paid", "email", "referral". |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| rows | Yes |