get_ga4_data

Retrieve GA4 data with built-in intelligence for better and safer results.

Returns on success: {"data": [...], "metadata": {...}, "_skills_tip": "..."}. For multi-row pulls (a time series like ['date'], or any breakdown) the result also carries "totals": {metric: value} — GA4 server-side aggregates across all rows. Read the period figure from "totals"; do NOT sum the rows yourself. (Additive metrics sum; rate metrics are period-computed by GA4.) Returns on volume warning: {"warning": "...", "estimated_rows": N, "suggestions": [...]} Returns on error: {"error": "..."}

CRITICAL WORKFLOW — follow this sequence every time:

1. DISCOVER FIELDS: NEVER guess dimension or metric names. Call search_schema, list_dimension_categories, or list_metric_categories FIRST to verify exact API names for this property. Guessing costs you a failed round-trip.

2. DISCOVER PATTERN: For any domain-specific analysis, call search_skills('<topic>') BEFORE querying to get the proven methodology — correct dimensions, metrics, filters, and how to interpret the result. One extra call prevents multiple failures. Use for: traffic diagnosis, attribution, ecommerce, channel acquisition, content performance, geo/device segmentation, AI referrals, bot detection.

3. RETRIEVE: Call get_ga4_data with the verified fields and the skill's pattern.

4. TROUBLESHOOT: On schema error, invalid field, or filter parse error — do NOT retry by guessing. Your training may predate current GA4 (UA was sunset 2023-07-01). Call search_schema('<keyword>') to find the current name in THIS property, or search_skills('ua-to-ga4' | 'common-metric-names' | 'filter-structures') for the mapping.

FIELD NAMES — GA4 API names vs common wrong guesses:

• 'screenPageViews' not 'uniquePageviews' or 'pageViews'

• 'totalUsers' not 'users'

• 'keyEvents' not 'conversions' or 'goalCompletionsAll'

• 'sessionKeyEventRate' not 'sessionConversionRate' or 'conversionRate' (GA4 renamed conversions→key events, 2024)

• 'userEngagementDuration' not 'timeOnPage' or 'avgTimeOnPage'

• 'averageSessionDuration' not 'avgSessionDuration'

• 'itemsViewed' not 'itemViews'

• 'ecommercePurchases' not 'purchases'

• 'sessionDefaultChannelGroup' not 'sessionDefaultChannelGrouping'

• 'sessionSource'/'sessionMedium' not 'source'/'medium'

• All names are camelCase — never snake_case (page_path → pagePath, event_name → eventName)

• 'bounceRate' and 'newUsers' are correct as-is

DATE RANGES:

• Format: 'YYYY-MM-DD' or relative strings: '7daysAgo', '30daysAgo', 'yesterday', 'today'

• 'NdaysAgo' counts back from today, excluding today. 'yesterday' = last complete day.

• Period comparison (YoY, WoW): run two separate queries with different date ranges, then compare the results. The API does not support multi-period in one call.

SCOPE RULES — incompatible combinations return a 400 error:

• Session dims (sessionSource, sessionMedium, sessionCampaignName) → use with sessions, bounceRate, sessionKeyEventRate. NOT with eventCount.

• Event dims (eventName) → use with eventCount. NOT with sessions.

• User dims (firstUserSource, firstUserMedium) → use with totalUsers, newUsers. NOT sessions.

• Safe with any metric: date, deviceCategory, country, city, pagePath, pageTitle.

FILTER STRUCTURE:

• Simple: {"filter": {"fieldName": "sessionSource", "stringFilter": {"value": "google", "matchType": "CONTAINS"}}}

• AND: {"andGroup": {"expressions": [{"filter": {...}}, {"filter": {...}}]}}

• OR: {"orGroup": {"expressions": [{"filter": {...}}, {"filter": {...}}]}}

• NOT: {"notExpression": {"filter": {...}}}

• Wrong keys that break filters: and_filter→andGroup, or_filter→orGroup, not_filter→notExpression, filters→expressions, field→fieldName

Args: dimensions: GA4 dimension names (verified via schema tools, e.g. ["date", "city"]). metrics: GA4 metric names (verified via schema tools, e.g. ["totalUsers", "sessions"]). date_range_start: Start date — 'YYYY-MM-DD' or '7daysAgo', '30daysAgo', 'yesterday'. date_range_end: End date — 'YYYY-MM-DD' or 'yesterday', 'today'. dimension_filter: Optional FilterExpression dict. camelCase and snake_case both accepted. limit: Max rows to return. Defaults to 1000. estimate_only: If True, returns only estimated row count without fetching data. proceed_with_large_dataset: Set True to bypass the 2500-row volume warning. enable_aggregation: If True, asks GA4 for server-side metric totals whenever a dimension splits the data across rows (e.g. a 7-day ['date'] pull), returned in a "totals" block so the model needn't sum rows. Default True. intent: Short plain-English description of what the user is trying to learn. E.g. "which channels drive most signups", "bot traffic audit for last month".