web_analytics_overview
How is my website traffic doing? Sessions, users, conversions, conversion rate, bounce rate, session duration and engagement from your web-analytics source (GA4 or Adobe Analytics) for one segment — optionally restricted to one country or broken down by country / device / landing page / traffic source / keyword / content category / intent — or, for the conversion metrics, by rank bucket ("conversions by rank bucket for pages containing /compare" is metrics:['conversions'], breakdown:'rank_bucket', page:'/compare') — and compared to a prior period. Pass goal (a tenant goal name like "Purchase", or goalN id) to make conversions and conversion_rate goal-specific — "purchase conversion rate for each product category" is goal:'Purchase', metrics including conversion_rate, breakdown:'category', sort_by:'conversion_rate'. The goal rate is governed and USER-based (completions ÷ unique users), the same basis QWA displays; NEVER derive a rate as conversions ÷ sessions. Follow-up drills retain scope by passing the selected category, subcategory, intent, page, or keyword while setting breakdown to the requested row type (for example breakdown:'page', category:'Login and Account'). Full page URLs are exact; path-only page scopes use contains matching because the underlying facts store absolute URLs. For a day/week/month/quarter trend by traffic source, call this tool exactly once with granularity plus breakdown:'source_medium'; it returns a single governed multi-source series instead of requiring one call per source or bucket. DEFAULT SCOPE mirrors QWA-as-built at CARD level, not per metric. With NO conversion metric requested, every metric is read at QWA Growth Trends' default scope — web search type + google/organic — so totals match an untouched QWA card, NOT raw GA4 all-source numbers. Requesting ANY of conversions, conversion_rate, total_value or transactions flips the WHOLE result to All traffic sources, behavioral metrics included, exactly as QWA's own "Switched to All traffic sources" does — so sessions/users are drawn from the same traffic population the rate's DENOMINATOR uses. The displayed conversions count remains QWA's All-Conversions total and is NOT the rate's numerator, so conversions / users does not reproduce the displayed rate; never derive a rate that way, and read metricDatasets for each metric's source. transaction_revenue does NOT flip the card (QWA has that entry commented out). Every result echoes the effective scope in appliedScope. A source_medium breakdown enumerates sources instead of pinning organic. This is the BEHAVIORAL / on-site lens (what visitors did once they arrived), NOT GSC clicks / impressions / rankings (use search_performance) and NOT market share vs competitors. ALWAYS per segment — called without one it lists the available segments.
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": {
"date_range": "<date_range>"
},
"name": "web_analytics_overview"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| geo | No | Break the numbers down by visitor location. Country only (state/city visitor geo is temporarily unavailable — see breakdown). | |
| goal | No | Tenant conversion goal — its name (e.g. "Purchase") or goalN id. Makes `conversions` that goal's completion count and `conversion_rate` that goal's USER-based rate (completions ÷ unique users — the exact basis QWA displays; NEVER derive completions ÷ sessions). "Purchase conversion rate by product category" is goal:"Purchase", metrics including conversion_rate, breakdown:"category", sort_by:"conversion_rate". An unknown goal returns the tenant's goal list. | |
| page | No | Restrict to one page selected in a previous drill. A full absolute URL is exact; a path-only value uses contains matching across stored full URLs. This filters the data; use breakdown to choose the returned row type. | |
| top_n | No | How many rows to return when breakdown is set. | |
| device | No | Restrict to one device type. | |
| intent | No | Restrict to one exact intent selected in a previous drill, e.g. "Brand". | |
| country | No | Restrict to one country, e.g. "United States". Filters the data, distinct from breaking down BY country. | |
| keyword | No | Restrict to one exact keyword/query selected in a previous drill. | |
| metrics | No | Which engagement metrics to return: sessions, users, conversions, conversion rate, bounce rate, session/page duration, unique pageview count, total value, transactions, transaction revenue, total/average events, or "engagement". Defaults to sessions, users, conversions, conversion rate and engagement. "engagement" expands to average session duration + bounce rate. Do not add a metric merely to rank a breakdown; use sort_by for that. | |
| segment | No | Tracked segment ID; omit to get the list of available segments | |
| sort_by | No | Metric that determines top-N row ordering when breakdown is set. It must also be present in metrics. Defaults to the first requested metric. Set sort_by:"conversions" for top pages/categories by conversions even when sessions or other context metrics are also returned. | |
| category | No | Restrict to one exact content category selected in a previous drill, e.g. "Login and Account". For pages within that category, combine with breakdown:"page". | |
| breakdown | No | Return a top-N breakdown across this attribute instead of a single total — e.g. sessions by device, landing page, traffic source (source_medium), keyword, content category/subcategory, intent (keyword group), or country. rank_bucket buckets the CONVERSION metrics (conversions/transactions/transaction_revenue, or goal-scoped conversions) by Google rank band and combines with a page scope; behavioral metrics (sessions, users, engagement) cannot be bucketed by rank and are rejected with a note. (Visitor state/city breakdowns are temporarily unavailable due to a model-level geo bug.) | |
| date_range | Yes | Explicit date range, e.g. "2026-05-01 to 2026-05-31". Both endpoints are INCLUSIVE — the END day is covered (a 7-day range = 7 days). Quattr weeks run Sunday–Saturday; for "last week" use the most recent complete Sun–Sat span. | |
| granularity | No | Return a whole-domain TIME SERIES bucketed by day / week / month / quarter instead of a single total — e.g. "weekly sessions over the last 13 weeks". It may be combined with breakdown:"source_medium" for one governed multi-source series; other breakdowns and comparison_range are unsupported in trend mode. | |
| subcategory1 | No | Restrict to one exact level-1 content subcategory selected in a previous drill. | |
| subcategory2 | No | Restrict to one exact level-2 content subcategory selected in a previous drill. | |
| date_range_mode | No | REQUIRED when granularity is set. Use "calendar" for YTD or another explicit calendar period: keep the requested start and return only complete buckets inside it. Use "rolling" for "last N days/weeks/months/quarters": preserve N complete buckets by shifting the full window backward when needed. | |
| comparison_range | No | Explicit comparison range for period-over-period, e.g. "2026-04-01 to 2026-04-30" | |
| source_medium_values | No | For a source_medium breakdown or time series, restrict the result to these exact QWA traffic-source values in this order, e.g. ["(direct) / (none)", "google/organic"]. Values are the QWA-curated source_medium values exactly as stored (low-volume sources may be grouped under an "other" bucket) — there is no "AI", "LLM", or other channel-grouping bucket among them, so never invent one; resolve real values with list_filter_values(traffic_source). Explicit values replace top-N source ranking so unrelated high-volume sources cannot displace the requested rows or series; values matching nothing are echoed back in unmatchedSourceMediumValues rather than silently dropped. |