Analytics Insights

Analytics Insights

Operator skill for the Google measurement stack — GA4, GTM, Search Console, and BigQuery — driven directly from chat. Build a tracking plan, run reports, mark conversions, audit existing setup, and query the warehouse without leaving the conversation.

Out of scope — defer to other skills

GSC and HyperSEO overlap on search-performance data. Rule of thumb: use GSC here for the user's own site's impression / click / position data. Use HyperSEO (in seo-research) for keyword research, competitor data, AI-search visibility.

Requirements

• Hyper MCP installed and connected. https://app.hyperfx.ai/mcp
• At least one of these connected at https://app.hyperfx.ai/apps:
  • Google Analytics — GA4 reports, custom metrics / dimensions, key-event (conversion) management.
  • Google Tag Manager — tag / trigger / variable / workspace / version management.
  • Google Search Console — search-performance data, sitemaps, URL inspection.
  • BigQuery — SQL queries against the GA4 export (or any other dataset).

If google_analytics_ga4_reports_run, google_tag_manager_tags_manage, google_search_console_performance_get and database_query are all not found, the integration to connect is one of Google Analytics, Google Tag Manager, Google Search Console or Database (a BigQuery connection).

How to run the tools in this skill

Every tool in this skill is named by its canonical tool name. Run it with the call your surface gives you:

If a tool is not found: in Hyper chat, find its toolkit id with discover_toolkits and pass it to enable_toolkit. On an MCP client or the CLI, tell the user which integration to connect in Hyper.

Tool surface

Critical rules

1. GA4 property IDs — arg name differs by tool. Three patterns: (a) Reporting tools (run_ga4_report, get_property) take property_id="properties/123456789". (b) Create and list tools (create_key_event, list_key_events, create_custom_dimension, list_custom_dimensions, etc.) take parent="properties/123456789". (c) Get/update/delete tools operate on a specific resource and take name= with the full resource path (e.g. "properties/123456789/keyEvents/12345"). All three need the properties/ prefix in some form — passing a bare numeric ID silently fails. When in doubt, check the tool's schema for which arg is marked required.
2. Date ranges are inclusive on both ends. start_date="2026-04-01" and end_date="2026-04-30" returns 30 days, not 29. Same for relative dates: 7daysAgo to today is 8 days, not 7.
3. GA4 sampling kicks in above ~10M events. For high-volume properties, the GA4 API silently samples results. If precision matters (board reporting, financial attribution), use the BigQuery GA4 export instead — see references/bigquery-ga4-export.md.
4. Conversions in GA4 are "key events". GA4 renamed "conversions" to "key events" in 2024. The tools reflect this — use google_analytics_key_events_create to mark an event as a conversion. Don't get confused by older docs.
5. GTM changes need a workspace + version + publish. Tags / triggers / variables created in a workspace are not live until the workspace is committed to a new version and that version is published. Use google_tag_manager_workspaces_manage → modify → google_tag_manager_versions_manage (create) → publish.
6. GSC data has a 2–3 day lag. Don't query "yesterday" in GSC and expect data — query 3+ days back for stable numbers. GA4 has a 24-48h lag for some metrics.
7. Apple Mail Privacy Protection inflates GA4 "engaged" sessions from email. Don't trust email-driven engagement numbers in GA4 alone — cross-reference with the email provider's own click data.

Workflow — pick the right path

The skill covers four distinct jobs. Pick first; the workflows are different.

Phase R — Run a report (most common path)

Warehouse option: When the workspace has an analytics warehouse connection, discover its tables and schema and query them through database_query. Read Warehouse Data Status for the selected connection and report its last successful refresh; do not assume an hourly cache or unsampled data. Otherwise use google_analytics_ga4_reports_run for GA4 and google_search_console_performance_get for GSC. Keep account IDs, dates and metric definitions explicit.

1. Confirm the property. google_analytics_accounts_list() → google_analytics_properties_list(filter="parent:accounts/<account_id>"). Ask the user to pick if there are multiple. Save the properties/<id> for the rest of the conversation.
2. Pick the date range. Always confirm. "Last 30 days" is start_date="30daysAgo", end_date="yesterday" (avoid today — partial-day data is unstable).
3. Pick metrics + dimensions. Don't blast 12 metrics × 6 dimensions in one report — the result is unreadable. Pick the 2–3 metrics that answer the user's question and the 1–2 dimensions that segment them meaningfully.
4. Run the report.

Copy code
google_analytics_ga4_reports_run(
  property_id="properties/123456789",
  start_date="30daysAgo",
  end_date="yesterday",
  metrics=["activeUsers", "sessions", "conversions", "totalRevenue"],
  dimensions=["sessionDefaultChannelGroup", "deviceCategory"],
)

5. Present results as a table. Always show the raw numbers alongside any interpretation. "Organic search drove 12,400 sessions (+18% MoM)" beats "organic was up."
6. One follow-on if the data flags it. If a metric stands out (e.g., conversion rate dropped 40% on mobile), run one targeted follow-up report — don't speculate.

Common GA4 metrics & dimensions

The GA4 API uses camelCase names. The most useful:

Metrics: activeUsers, sessions, screenPageViews, bounceRate, engagementRate, averageSessionDuration, conversions, eventCount, totalRevenue, transactions, purchaseRevenue, userEngagementDuration.

Dimensions: country, city, deviceCategory, operatingSystem, browser, sessionDefaultChannelGroup, sessionSource, sessionMedium, sessionCampaignName, pagePath, eventName, date, hour, landingPage.

For the full list, the user can browse the GA4 Data API reference.

Phase T — Set up tracking

The GA4 API can create properties, data streams, key events, custom metrics, and custom dimensions — but it can't deploy GTM tags into the page. That step is GTM-side (or hard-coded in the site). The skill workflow:

1. Tracking plan first. Define what events you need to fire, where they fire, and which ones are conversions (key events). Full template in references/ga4-tracking-plan.md.
2. GA4-side setup — create custom dimensions / metrics, mark key events:

Copy code
google_analytics_custom_dimensions_create(
  parent="properties/123456789",
  parameter_name="plan_tier",
  display_name="Plan Tier",
  scope="EVENT",
)

google_analytics_key_events_create(
  parent="properties/123456789",
  event_name="purchase",
  counting_method="ONCE_PER_EVENT",
)

3. GTM-side setup — create/update tags + triggers + variables in a workspace, then version + publish:

Copy code
google_tag_manager_workspaces_manage(operation="create", account_id="...", container_id="...", name="purchase-tracking-v3")

google_tag_manager_tags_manage(operation="create", workspace_path="...", tag_definition={...})
google_tag_manager_triggers_manage(operation="create", workspace_path="...", trigger_definition={...})
google_tag_manager_variables_manage(operation="create", workspace_path="...", variable_definition={...})

google_tag_manager_versions_manage(operation="create", workspace_path="...", version_name="purchase-tracking-v3")
# then publish via the GTM UI or version operation

4. Validate — see Phase A.

Phase A — Audit (the existing setup is broken or suspect)

Most "our analytics is wrong" complaints are one of:

Detailed audit walkthrough in references/gtm-audit.md.

Phase B — BigQuery GA4 export (precision / cross-source analysis)

For unsampled data, custom attribution, joining GA4 with order-DB / CRM data, or cohort analysis. Requires the GA4 → BigQuery export to be turned on in the GA4 admin (free for standard properties since 2023).

Copy code
bigquery_execute_query(
  query="""
    SELECT
      event_date,
      COUNT(DISTINCT user_pseudo_id) AS users,
      COUNTIF(event_name = 'purchase') AS purchases,
      SUM(IF(event_name = 'purchase', ecommerce.purchase_revenue, 0)) AS revenue
    FROM `your-project.analytics_123456789.events_*`
    WHERE _TABLE_SUFFIX BETWEEN '20260401' AND '20260430'
    GROUP BY event_date
    ORDER BY event_date
  """
)

Schema, common queries, and the full attribution-modeling workflow in references/bigquery-ga4-export.md.

Output standards

• Always present numbers as tables, not prose. "12,400 sessions, 8.2% bounce, 1.4% conversion" → markdown table.
• Always include the date range in the report header. "Apr 1–30, 2026" — undated numbers are useless.
• Always include the property / site the report came from. Multi-property organizations get burned by this constantly.
• Annotate sampling. If GA4 returns a samplesReadCount < samplingSpaceSize, say so explicitly. The user needs to know whether to trust the number for finance / board reporting.
• Distinguish "ratio metric" from "summable metric". Bounce rate, engagement rate, conversion rate are ratios and don't sum — present them as one number, not a column total.

Reference workflows