AI Traffic Audit (GA4)
Purpose
Show a marketer how much of their website traffic comes from AI assistants, which AI platforms send it (ChatGPT, Gemini, Perplexity, Claude, Copilot, Meta AI, Grok, DeepSeek, Mistral, Poe, You.com), and exactly which landing pages each platform sends visitors to — with engagement, key events and change vs the previous 30 days. The dashboard shows every AI platform by its logo so the page × platform picture is readable at a glance.
Connectors required
This skill uses the following TMR connector:
- Google Analytics 4 (
ga4)
The runtime procedure below verifies it is available before doing any analytical work. Do not attempt to proceed with partial connector availability.
Files in this skill
queries.json— the four locked query templates (field IDs + relative date specs).config.json— saved end-user settings (accounts, auto-confirm).references/build_dashboard.py— classifies GA4 session sources into AI platforms, computes KPIs and renders the dashboard.references/dashboard_template.html— the dashboard scaffold (layout, CSS, charts). Do not edit per run.references/logos/— AI platform logos + GA4 logo. The script embeds them as data URIs so the dashboard is self-contained.
Runtime procedure
Follow these steps in order. Do not skip steps. Do not rearrange.
1. Check that TMR's tools are available
Inspect your available tools. The current Two Minute Reports MCP exposes these tool names: verify_team_details, list_connectors, get_connector_accounts, get_connector_query_schema, validate_query, run_query. The prefix may vary — users name their MCP connections differently (e.g., "Two Minute Reports", "TMR", "TwoMinuteReports", or a custom name). Match by tool function and the Two Minute Reports MCP server (URL: https://mcp.twominutereports.com/mcp), not by exact prefix. If the tools are deferred, load them with your tool-search tool first.
If none of these tools are present, tell the user:
"This skill needs Two Minute Reports to be connected to your Claude account, but I don't see it in your available tools.
Two Minute Reports is an analytics platform that lets you query your marketing data (ads, analytics, e-commerce, etc.) from inside Claude. You'll need to connect it once, then this skill (and any other TMR skills) will work.
Here's the setup guide: https://twominutereports.com/help/mcp/claude
Once it's connected, run this skill again."
If a suggest_connectors capability is available, also use it to surface a one-tap connect option for the Two Minute Reports MCP. Then stop.
2. Verify team and plan status
Call verify_team_details.
- Multiple teams → present them and ask which to use (flag any
cancelledteam). Store the chosenteamId. - One team → use it and tell the user which team is active.
active,in_trial,non_renewingare fine. Ifcancelled, stop: "Your Two Minute Reports plan is cancelled, so I can't pull data. Reactivate it at hub.twominutereports.com/billing, then run this skill again."- Auth/permission/session error or no teams → "Two Minute Reports is connected, but I couldn't verify your team details — your session may have expired or the connection needs to be re-authenticated. Please reconnect Two Minute Reports with the account that holds your TMR team, then run this skill again. Setup reference: https://twominutereports.com/help/mcp/claude" (trigger
suggest_connectorsif available). Stop. - Other failure → "Couldn't reach Two Minute Reports right now — please try again in a moment." Stop.
3. Verify GA4 is provisioned in TMR
Call get_connector_accounts(teamId, connectorId:"ga4", status:"enabled").
- At least one account → continue.
- No accounts → "This skill needs Google Analytics 4 to be set up inside Two Minute Reports, but it isn't connected with an enabled property yet. Please open Two Minute Reports, add Google Analytics 4 (and enable a property), then come back and run this skill again." Stop.
- Call fails entirely → treat like a step 2 session failure.
4. Locate skill folder and load configuration
Find this skill's install folder (<install-path>):
/mnt/skills/user/tmr-ga4-ai-traffic-audit/- else
find / -type d -name "tmr-ga4-ai-traffic-audit" 2>/dev/null | head -1 - else: use the fallback query templates at the bottom of this file, skip config read/write and the save prompt, and build the dashboard by hand following the layout described in step 6.
Read <install-path>/config.json.
saved: true→ "Using your saved configuration: property . Say 'change config' if you want to update these." Use the storedaccountsandauto_confirm_query.- Otherwise → reuse the step 3 response, list the GA4 properties and ask "Which GA4 property would you like to audit?" (one property per run gives the cleanest page matrix; if the user picks several, sum them). No currency is needed — this skill has no monetary metrics.
- Corrupt/unreadable config → "Couldn't read your saved settings — let's set them again." and run the collection flow.
5. Build, validate, and run the queries
Load the four templates from <install-path>/queries.json.
a. Resolve dates from today's real date (GA4 same-day data is partial, so end yesterday):
last_n_days {n, end_offset_days}→endDate= today − end_offset_days,startDate= endDate − (n − 1). With n=30, offset 1: the 30 full days ending yesterday.previous_n_days {n, offset_days}→endDate= today − offset_days,startDate= endDate − (n − 1). With n=30, offset 31: the 30 days immediately before the current window.
b. Assemble one ga4 connector entry with accountIds = the selected property ID(s) and four queries, each {title, query:{metrics, dimensions, dateRange, filters, sort}}. Keep the titles exactly as in queries.json. Raw field IDs, no prefix.
c. Validate with validate_query(teamId, userQuery:<the user's request>, connectors:[…], skillId:"tmr-ga4-ai-traffic-audit"). On errors, do not run — explain briefly that the GA4 schema may have changed and suggest contacting the skill author. Stop.
d. Confirm (skip if auto_confirm_query is true): "I'll pull GA4 sessions, users, engaged sessions, key events and engagement time by session source and landing page for –, a daily trend, the site total, and the previous 30 days (–) for comparison, from . OK?" Wait for yes.
e. Run run_query(teamId, connectors:[…], limit:5000, skillId:"tmr-ga4-ai-traffic-audit").
- If the result comes back inline, save the full JSON response to
ai_traffic_result.jsonin your working directory. - If it is too large and returned as a stored file path, use that path directly — do not load it into context.
6. Produce the dual output
First, render the dashboard and get the numbers:
python3 <install-path>/references/build_dashboard.py \
--input <result json path> \
--out <outputs dir>/ai-traffic-audit-<YYYY-MM-DD-HHMM>.html \
--account "<property label>" \
--window "<start> to <end>" \
--compare "<prev start> to <prev end>" \
--run-time "<YYYY-MM-DD HH:MM in the user's timezone>"
The script prints a JSON summary (KPIs, per-platform totals, previous-period sessions, top pages per platform, top pages with platform mix). Use only that summary for the insights — do not re-read the raw rows. Never pass --demo for a real run.
AI platform matching (in the script): a session counts as AI traffic when its GA4 session source contains chatgpt/openai (ChatGPT), gemini/bard (Gemini), claude.ai/anthropic (Claude), perplexity, copilot, meta.ai, grok/x.ai, deepseek, mistral, poe.com, you.com.
Insights (inline chat)
Write 150–300 words:
- Headline finding — the single most important thing.
- Supporting metrics — 2–3 numbers.
- Notable changes — biggest platform shifts vs the previous 30 days.
- Action — one concrete recommendation.
Match the tone, voice and structure of this template; fill the [brackets] with the user's data:
AI assistants sent [N] sessions to [site] in [reporting period] — [X%] of all [N] sessions, [up/down] [Y%] from [N] in [comparison period]. [Top platform] leads with [N] sessions ([X%] of AI traffic, [±Y%]), followed by [second platform] ([N]) and [third platform] ([N]); [remaining platforms] together sent [N].
AI visitors are [high/low]-quality traffic: [X%] engagement and [N] key events ([N] per session) [vs site context if known]. [Top page] captures [N] of the [N] AI sessions ([X%]); the rest is a long tail of [page type] pages, and platforms differ in where they send people — [platform A] favours [page examples], while [platform B] sends users to [page examples].
[Biggest shift]: [platform] moved from [N] to [N] ([±X%]) [and/while] [second shift].
Action: [one concrete step tied to the biggest finding — e.g. protect/expand the pages a growing platform cites, investigate a declining platform's landing pages, add clear answers/structured data to high-AI-traffic pages].
Also note in one sentence that some AI apps strip referrers, so their visits land in (direct) and are not counted — the figures are a floor.
Dashboard (artifact)
The HTML file from the script is the dashboard. Publish it as a new artifact each run (never overwrite an earlier one), titled:
AI Traffic Audit — <YYYY-MM-DD HH:MM> — <property label>
If you can publish artifacts, publish the file; otherwise deliver the HTML file to the user. It contains: a metadata header (GA4 logo, property, window, comparison window, run time), five KPI tiles (AI sessions with change, share of site sessions, AI users, AI key events, AI engagement rate), an AI platform leaderboard (one card per platform with its logo, sessions, share, change, engagement, key events, engagement time and top 5 pages), a stacked daily trend by platform, and a filterable Pages × AI platforms matrix with platform logos as column headers. Do not modify the template or logos; only the script fills the data.
If there is no AI traffic in the window, the dashboard shows an empty state — say so plainly in the insights and suggest checking a longer window or whether AI referrals are being grouped as (direct).
7. Save configuration (first run only, only if no saved config existed at start)
Ask:
"Want to save your settings for future runs? This skill can remember your GA4 property so you don't have to pick it every time — useful if you re-run this report regularly or use it in a workflow.
- Save property? (yes / no)
- Auto-confirm the query on future runs? (yes / no — saves a step but you won't see the query before it runs)"
If yes to either, write <install-path>/config.json:
{
"version": "1.0.0",
"saved": true,
"accounts": { "ga4": [{ "label": "...", "value": "..." }] },
"currency": null,
"auto_confirm_query": true,
"saved_at": "<ISO 8601 timestamp>"
}
Wrap the write in error handling. On failure: "Couldn't save your settings to disk — they'll be remembered for this conversation only. You'll be asked again next time you run this skill." On success: "Saved. Future runs of this skill will use these settings automatically. Say 'change config' inside the skill to update." Skip this step silently if <install-path> was not resolved.
Notes for end users
- The skill asks you to confirm the query before running it (unless auto-confirm is on).
- It always covers the last 30 full days vs the 30 days before. Need a different window? Ask for a different skill — skills stay specific so they're predictable.
- Every run produces both an inline insights summary and a new dashboard artifact from the same data.
- AI traffic is identified from GA4's session source. Visits from AI apps that don't pass a referrer show up as (direct) and can't be attributed, so treat the numbers as a minimum.
- Requires the Two Minute Reports MCP connected to Claude — see https://twominutereports.com/help/mcp/claude.
Query templates
(Fallback copy of queries.json in case the install folder can't be located at runtime.)
{
"queries": [
{"title": "AI Referral Source x Landing Page", "connectorId": "ga4",
"metrics": ["sessions", "total_users", "engaged_sessions", "key_events", "user_engagement_duration"],
"dimensions": ["session_source", "landing_page"],
"filters": [{"filterField": "session_source", "operator": "notEquals", "expression": "google"},
{"filterField": "session_source", "operator": "notEquals", "expression": "(direct)"},
{"filterField": "session_source", "operator": "notEquals", "expression": "bing"},
{"filterField": "session_source", "operator": "notEquals", "expression": "(not set)"}],
"sort": [{"sortField": "sessions", "direction": "desc"}],
"date_spec": {"type": "last_n_days", "n": 30, "end_offset_days": 1}},
{"title": "AI Referral Daily Trend", "connectorId": "ga4",
"metrics": ["sessions"], "dimensions": ["date", "session_source"],
"filters": "<same four session_source filters>",
"date_spec": {"type": "last_n_days", "n": 30, "end_offset_days": 1}},
{"title": "Site Total", "connectorId": "ga4",
"metrics": ["sessions", "total_users"], "dimensions": [], "filters": [],
"date_spec": {"type": "last_n_days", "n": 30, "end_offset_days": 1}},
{"title": "AI Referral Sources Previous Period", "connectorId": "ga4",
"metrics": ["sessions", "total_users", "key_events"], "dimensions": ["session_source"],
"filters": "<same four session_source filters>",
"date_spec": {"type": "previous_n_days", "n": 30, "offset_days": 31}}
]
}