Live

Open the stream

Open a website and choose the Live tab. The stream starts with the last 5 minutes of hits, newest on top, then adds each new hit as it arrives, usually within a second.

Each row shows the time, the hit type (pageview, event, append or error), the page or event name, the device, browser and country, a short visitor id, and an Entry label when the pageview came from outside the site. Click a row to see the query string, referrer, operating system, event metadata and the city-level location.

Live needs a signed-in session: open it from the dashboard while you are logged in. API keys cannot open it.

Check your own install

Open your website in another tab and turn on Only my traffic. The stream then keeps only the hits sent from the browser you are using, matched on your network address and browser. The 5 minutes of history loaded when the page opens are never marked as yours.

If nothing arrives, follow the quickstart to check the script tag.

Pause, filter and search

Pause freezes the list so you can read it. New hits wait behind a new button that resumes the stream and jumps back to the top. The type menu and the search box filter what is on screen by path, event, referrer, visitor, country or event metadata without changing what arrives. The counter shows hits per minute.

Workspace map

Choose Live in the sidebar, below All websites, to watch every website at once. Each hit with a location becomes a pulse in its website's colour and fades after 30 seconds. The globe turns slowly while nothing happens; drag it or use the arrow keys to look around. Small screens, reduced motion and browsers without WebGL get a flat map with the same pulses. Next to the map, Latest hits lists the newest 100 hits across all websites.

What is kept

Nothing new. The stream and the map are not stored anywhere: they show hits your reports already count, and they disappear when you close the page. Locations are city-level estimates from the network edge, not GPS. Only the owner of a website can open its stream or see it on the map, and shared dashboards have no Live tab. Reports keep working exactly as before.

Limits

• Live stays open in up to eight tabs per account. Opening a ninth disconnects the oldest, which shows a Reconnect button.
• The stream keeps the newest 500 hits on screen.
• A tab hidden for more than a minute disconnects, then catches up when you come back.

API

The Live tab runs on three routes. Tickets and history take the owner's Firebase ID token only; a management key gets 401 sign in required.

• POST /api/live/ticket with { "site": "<hostname>" }, or without site for every verified website you own, returns { ticket, expires_in, url }. A ticket opens one stream and expires after 60 seconds, and an account can hold 32 unused tickets before 429 too many live tickets. A site you do not own returns 404 unknown site, an unverified one 403.
• GET /api/live/ws?ticket=<ticket> is the WebSocket: connect to wss://clicktag.io followed by the returned url. The ticket is the only credential. A request that is not a WebSocket upgrade gets 426, a malformed ticket 400, and an unknown, expired or used ticket 403.
• GET /api/live/recent?site&since&limit returns { since, until, hits }: stored hits newer than since, newest first. since is unix milliseconds, 5 minutes ago by default and never more than 15 minutes back. limit defaults to 200 with site and 100 without, up to 500.

The socket sends JSON text messages:

• {"t":"hello","scope":"site","site":"your-domain.example","since":1789520400000,"sockets":1} once. scope is all with site: null for every website, and sockets counts the open streams on your account, this one included.
• {"t":"hits","hits":[...],"dropped":0} as hits arrive. The first hit goes out at once and anything in the next 50 ms follows together. When more than 200 hits wait, the oldest are skipped and dropped on the first message counts the ones this socket would have received; that message can have empty hits.
• {"t":"bye","reason":"too_many_tabs"} just before the server closes the oldest stream with code 4001, when a ninth one opens.

Send ping to get pong; a message over 1024 bytes closes the socket with code 1009. Each hit has site, ts (unix milliseconds), type, id, orig, path, query, ref, event, meta, error, dur and scroll (appends only, otherwise null), country, device, browser, os, unique (1 for an entry), visitor (the first 8 characters of the daily visitor hash) and me. Hits on the socket also carry loc (lat, lng, city, region) when a location is known; hits from recent have me: false and no loc.

A data center that finds nobody watching a website stops sending its hits for 30 seconds, so the first half minute after you connect can miss a few. The dashboard asks recent again 35 seconds after hello to fill that gap. The full schemas are in the OpenAPI file.