exploring-live-traffic

What is happening on a website this minute — how many people are on it, what they are looking at, which bots are crawling it — in a view that never reaches back further than the last half hour.

WHEN TO USE

SCOPE

USE FOR

Check who is currently active on a site in the last 30 minutes.
Find out which bots, like GPTBot or Googlebot, are crawling a site right now.
Turn a live traffic pattern into a longer-range chart or saved insight.
Filter the live view down to a single domain when several are tracked.

NOT FOR

Analyze historical, non-real-time web analytics trends (use the standard Web analytics tab instead).

This is a saved copy of the skill's SKILL.md instructions. It may differ from the upstream file or the version you install.

In this document (7)

Exploring Web analytics live traffic

The Web analytics Live tab (/web/live) shows real-time activity over a 30-minute sliding window plus a 60-second "users online" count. It is the place to answer "what is happening on my site right now?" — pageviews, named bots, devices, geo, top paths, top referrers, and a live event feed.

This skill teaches you (the agent) how to:

recognize a request that belongs on the Live tab
read the tile model (what each card shows, where the data comes from)
manipulate the only filter that exists (host)
build product-analytics insights that match a Live tile when the user wants longer time ranges or deeper drill-down than the live window offers

The Live tab is not a HogQL playground — its data comes from a livestream backed by short HogQL backfills. When the user wants to query "right now" data with HogQL, point them at the tab; when they want historical breakdowns, build an insight with the patterns below.

When to use this skill

Use this skill when the user:

asks "who is on my site right now?", "what is happening live?", "show me live traffic"
mentions the "Live" tab, the "Live dashboard", or the live page (/web/live)
asks about live bot traffic ("which bots are crawling me?", "is GPTBot scraping us?")
wants to filter live traffic by domain / host
wants to compare what they see on the Live tab to a longer time window — e.g. "the live tab shows GPTBot is hammering us, can you give me a 7-day chart of that?"

Do not use this skill for non-realtime web analytics work — for that, use the standard Web analytics tab (/web).

Tab structure

URL: /web/live

The tab has two filter affordances and a grid of tiles. Date range is fixed: 30 minutes sliding window for everything except "Users online" (last 60 seconds).

Filters

There is only one filter on the live tab: the host (domain) selector.

It comes from webAnalyticsFilterLogic.selectedHost.
It is shared with the rest of Web analytics, so changing it on /web propagates to /web/live and vice-versa.
It is gated by feature flag WEB_ANALYTICS_LIVE_DOMAIN_FILTER. If the flag is off, no host filter UI is rendered and all tiles show data across every domain.
Setting the host filter narrows: the SSE stream, the HogQL backfill queries (so the initial 30 min is host-scoped), and the "users online" count.
There is no date picker, no compare control, no property filters, no test-account filter on the Live tab. Do not promise the user controls that don't exist.

When the user asks "filter live traffic by domain <host>", direct them to the Domain selector at the top of the Live tab. There is no URL param to set it directly — it persists in localStorage via webAnalyticsFilterLogic.

Stat cards (top strip)

Card	What	Window
Users online	Distinct device IDs seen in the last 60 seconds	60s
Unique visitors	Distinct device IDs in the last 30 min	30m
Pageviews	`$pageview` count in the last 30 min	30m

Content cards

Card	What	Notes
Active users per minute	Bar chart, new vs returning visitors	last 30 min
Top pages	Animated leaderboard, `$pathname` + view count	top 10, 30 min
Top referrers	Animated leaderboard, `$referring_domain`	top 10, 30 min
Devices	Breakdown bars, `$device_type`	top 6 + Other
Browsers	Breakdown bars with logos, `$browser`	top 6 + Other
Top countries	Breakdown bars, `$geoip_country_code`	top 6 + Other; replaced by a Country/City tab card if `WEB_ANALYTICS_LIVE_CITY_BREAKDOWN` is on
Bot requests per minute	Bar chart, bot events / minute	flag `WEB_ANALYTICS_BOT_ANALYSIS`
Bot traffic	Named bots ranked by event share, with category tag	flag `WEB_ANALYTICS_BOT_ANALYSIS`; rows are clickable and open an insight for that specific bot
Countries (world map)	SVG world map heat	flag `WEB_ANALYTICS_LIVE_MAP`
Live events	Streamed event feed (event, person, URL, timestamp)	last 50 events

Every tile (except the live event feed and world map) has an "Open as new insight" button that opens a 7-day Trends query in product analytics. The bot traffic tile rows are also individually clickable — clicking a bot row opens a single-bot trend.

Bot detection model

Bots are detected server-side. Three virtual properties are attached to the event before it lands in ClickHouse:

$virt_is_bot — boolean, true if classified as a bot
$virt_bot_name — string, the bot's display name (e.g. Googlebot, GPTBot, Claude, Lighthouse, HeadlessChrome)
$virt_traffic_category — string, the category key: ai_crawler, ai_search, ai_assistant, search_crawler, seo_crawler, social_crawler, monitoring, http_client, headless_browser, no_user_agent, regular

The Live bot tiles count "bot-eligible" events: $pageview, $pageleave, $screen, $http_log, $autocapture. $http_log is included because most bots emit server-side HTTP logs rather than JS pageviews.

Building product-analytics queries that mirror the Live tab

When the user wants a longer window, a saved insight, a dashboard tile, or to share a view of what's on the Live tab, build a Trends insight. The "Open as new insight" buttons in the UI use exactly these recipes:

Bot traffic breakdown (matches the bot tile header)

A single chart of all bots over time, broken down by name. This is the canonical "who's crawling me?" view.

{
  "kind": "TrendsQuery",
  "interval": "hour",
  "dateRange": { "date_from": "-7d" },
  "series": [
    {
      "kind": "GroupNode",
      "custom_name": "Requests",
      "operator": "OR",
      "math": "total",
      "nodes": [
        { "kind": "EventsNode", "event": "$pageview", "math": "total" },
        { "kind": "EventsNode", "event": "$pageleave", "math": "total" },
        { "kind": "EventsNode", "event": "$screen", "math": "total" },
        { "kind": "EventsNode", "event": "$http_log", "math": "total" },
        { "kind": "EventsNode", "event": "$autocapture", "math": "total" }
      ]
    }
  ],
  "properties": [{ "key": "$virt_is_bot", "value": ["true"], "operator": "exact", "type": "event" }],
  "breakdownFilter": {
    "breakdown": "$virt_bot_name",
    "breakdown_type": "event",
    "breakdown_limit": 25
  },
  "trendsFilter": { "display": "ActionsBarValue" }
}

Single bot drill-down (matches a clicked bot row)

{
  "kind": "TrendsQuery",
  "interval": "hour",
  "dateRange": { "date_from": "-7d" },
  "series": [
    /* same combined "Requests" GroupNode as above */
  ],
  "properties": [
    { "key": "$virt_is_bot", "value": ["true"], "operator": "exact", "type": "event" },
    { "key": "$virt_bot_name", "value": ["GPTBot"], "operator": "exact", "type": "event" },
    { "key": "$virt_traffic_category", "value": ["ai_crawler"], "operator": "exact", "type": "event" }
  ],
  "trendsFilter": { "display": "ActionsLineGraph" }
}

The category filter is optional — include it when the user asks about a specific bot+category combo (Lighthouse · headless_browser is a different signal from Lighthouse · monitoring).

Bot category breakdown (matches the bot events chart tile)

Use breakdown by $virt_traffic_category instead of $virt_bot_name when the user wants "AI crawlers vs SEO crawlers vs everything else" rather than per-bot rows.

Top pages / referrers / devices / browsers / countries

For non-bot tiles, use $pageview with math: unique_users, breakdown by the underlying property:

Tile	breakdown property	display
Top pages	`$pathname`	`ActionsBarValue`
Top referrers	`$referring_domain`	`ActionsBarValue`
Devices	`$device_type`	`ActionsPie`
Browsers	`$browser`	`ActionsPie`
Countries	`$geoip_country_code`	`WorldMap`

Always inherit the live tab's host filter when the user is asking about a specific domain — add { "key": "$host", "value": ["<host>"], "operator": "exact", "type": "event" } to properties.

Defaults to use

dateRange.date_from: -7d unless the user names a window — the live view itself is 30 min, but the user is almost always asking about a longer window when they request an insight version.
interval: hour for 7-day windows, minute only for windows under a day, day for windows beyond 14 days.
Always inherit the host filter when one is set on the Live tab. Don't drop it silently — that changes the answer.

Common requests and the right move

User says	Right move
"What's happening on the site right now?"	Send them to `/web/live`
"Filter live traffic to `example.com`"	Use the Domain selector at top of `/web/live`
"Show me bots crawling us in the last 30 min"	`/web/live` → Bot traffic tile
"Show me bots crawling us this week"	Build the "Bot traffic breakdown" insight above with `date_from: -7d`
"How much is GPTBot hitting us?"	Build the "Single bot drill-down" insight, set `$virt_bot_name` to `GPTBot`
"Why is the live tab showing X but my dashboard shows Y?"	The live tab is a 30-min sliding window over events; dashboards aggregate over the picked range. They are not directly comparable beyond the last 30 min.
"Add a date range to the live tab"	The Live tab has no date picker — for ranges, build a Trends insight using the patterns above
"Filter live traffic by browser / device / country"	Not supported — only the host filter exists. Build a Trends insight with the relevant breakdown + filter instead

Gotchas

Bot virtual properties ($virt_*) only exist on events processed by the bot classification step. They are not retroactive — events from before the classifier shipped will not have them. Keep dateRange.date_from within the last few months for reliable bot results.
$http_log events come from server-side log capture, not from posthog-js. If a project does not emit $http_log, bots that don't run JS (most crawlers) will be invisible to the bot tiles.
The 30-minute window is a sliding aggregation over an in-memory buffer in the browser — refreshing the page replays the backfill HogQL, not the SSE stream. Do not interpret a brief "0" right after page load as a real drop.
The host filter strips the protocol — pass example.com, not https://example.com.
Tile order is persisted per-team in localStorage (under feature flag WEB_ANALYTICS_LIVE_EDIT_LAYOUT). If a user's layout looks different from yours, it is not a bug.

This skill ships inside the PostHog AI Plugin. Listed package contents include 3 slash commands, 1 agent, hooks and an MCP server. Installed components and skill versions may vary by AI tool.

Install just this skill

Run this outside your AI tool, using Node.js 22.20.0 or newer. Skills CLI 1.7.2 skips skill selection; prompts cancel installation without an interactive terminal. If choosing Project when asked about installation scope, open your project's folder before running this.

Install checklist

Check selected tools if a picker appears; Claude Code may be unchecked under Additional agents. ↑/↓ moves, Space toggles selections, Enter confirms.
Without a tool picker, check Installing to: for your intended tool. Stop if it names a different tool.
If asked, choose Symlink (Recommended) for shared files or Copy to all agents for separate copies; review the summary before confirming installation.
Install the find-skills skill? defaults to Yes, adding another skill for all projects. Choose No if you don't want that extra installation.

Skills CLI 1.7.2 sends install data to skills.sh by default, including the source, skill names, target tools and file details; GitHub sources are reported only when GitHub confirms the repository is public, while other remote sources can also be reported. Confirmed-public GitHub sources also trigger a security-audit request. Before installing, set the environment variable DO_NOT_TRACK=1 or DISABLE_TELEMETRY=1 to disable both.

npx skills add posthog/ai-plugin --skill "exploring-live-traffic" --full-depth

After installing for Claude Code, open it in the installation project if you chose Project; Global makes the skill available across projects on this computer. Once Claude Code loads the skill, its description helps Claude decide when to use it.

If installation created a top-level skills folder that did not exist when your Claude Code session started, run /reload-skills in that session. Run it again after later changes in that folder.

Install the whole plugin

This route installs the posthog plugin package selected for your AI tool.

Claude Code

Add PostHog's marketplace, then install the plugin

Run both lines in a terminal. They install PostHog's posthog plugin: this skill, PostHog's other skills, and a connection to PostHog's hosted MCP server.

claude plugin marketplace add PostHog/ai-plugin

02
```
claude plugin install posthog@posthog
```

Installation and loading

The plugin installs for you in every project and loads the next time you start Claude Code, or after /reload-plugins in an open session.
To connect your PostHog account, start claude, type /mcp, select plugin:posthog:posthog and follow the browser prompts.

Good to know

The plugin includes PostHog's session-capture hook; PostHog's README says it sends sessions to LLM Analytics only when POSTHOG_LLMA_CC_ENABLED=true and POSTHOG_API_KEY are both set.
If you use the separate posthog-telemetry plugin, PostHog says to keep only one of the two, because both register the same hook.
On a self-hosted PostHog, this route's MCP connection won't reach your instance: the plugin's config is fixed to https://mcp.posthog.com/mcp, which routes to PostHog's US or EU region. POSTHOG_MCP_URL works only for the Gemini CLI extension.

View on GitHub

Same repository

adding-warehouse-person-properties
Sync columns from a synced data warehouse table onto PostHog person or group properties, so warehouse data becomes usable anywhere person and group properties already work: feature flag targeting, cohorts, insight filters and breakdowns, surveys, session replay filters, workflows, and the person profile. Use when the user wants to "add a person property from my warehouse", "enrich people with Stripe/Postgres/Salesforce data", "put ARR or plan tier on my persons", "target a feature flag by a warehouse column", "sync warehouse columns onto groups or organizations", or wants to inspect, backfill, disable, or debug an existing warehouse-backed person or group property.Read full description
analyzing-expensive-users
Analyze the most expensive users in AI observability and explain why they cost so much. Use when the user asks about top spenders, expensive users, per-user LLM cost, user-level cost drivers, or patterns behind high AI observability spend.Read full description
analyzing-experiment-session-replays
Analyze session replay patterns across experiment variants to understand user behavior differences. Use when the user wants to see how users interact with different experiment variants, identify usability issues, compare behavior patterns between control and test groups, or get qualitative insights to complement quantitative experiment results. Also covers pairing the observed behavior with a linked survey when the user wants qualitative feedback beyond what recordings show.Read full description
assessing-heatmaps
Assesses what a page's heatmap is telling you and recommends concrete changes. Pulls click / rageclick / scroll-depth data for a URL, names the hot elements by cross-referencing autocapture events on the same page, and can create a saved heatmap the user opens in PostHog, then summarizes the behavior and proposes improvements. TRIGGER when: user asks what a heatmap shows, why people aren't clicking something, where users rage-click, how far they scroll, what to change on a page based on heatmap/click data, or to 'analyze/assess/review the heatmap' for a URL. DO NOT TRIGGER when: the user only wants to create a saved heatmap screenshot with no analysis (use heatmaps-saved-create directly), or is asking about session replay in general (use investigating-replay).Read full description
auditing-endpoints
Audit every endpoint in a PostHog project for staleness, failed materialisations, and unused materialised versions. Use when the user asks "what endpoints can I clean up?", "are any of my endpoints broken?", "which materialised versions are still being called?", or wants a one-shot cleanup pass over the Endpoints product. Produces a prioritised report grouped by issue type, with recommended actions but does not modify anything without explicit confirmation.Read full description
auditing-experiments-flags
Audit PostHog experiments and feature flags for configuration issues, staleness, and best-practice violations. Read when the user asks to audit, health-check, or review experiments or feature flags, check flag hygiene, or verify experiment setup.Read full description

Exploring Web analytics live traffic

When to use this skill

Tab structure

Filters

Stat cards (top strip)

Content cards

Bot detection model

Building product-analytics queries that mirror the Live tab

Bot traffic breakdown (matches the bot tile header)

Single bot drill-down (matches a clicked bot row)

Bot category breakdown (matches the bot events chart tile)

Top pages / referrers / devices / browsers / countries

Defaults to use

Common requests and the right move

Gotchas

MCP connection required

Install just this skill

Install the whole plugin

Add PostHog's marketplace, then install the plugin

More skills

adding-warehouse-person-properties

analyzing-expensive-users

analyzing-experiment-session-replays

assessing-heatmaps

auditing-endpoints

auditing-experiments-flags