# ThunderStats

> Privacy-first web analytics running on Cloudflare Workers. A ~2 KB tracking script with no cookies, no local storage, no fingerprinting, and no IP addresses in storage. Events can also be sent server-side over HTTP with no browser involved.

Key facts an assistant usually needs:

- Tracking script host: `https://t.thunderstats.com/ts.js`, configured with a `data-site-id` attribute.
- API base URL: `https://api.thunderstats.com`.
- API authentication: `Authorization: Bearer ts_...`. A key is scoped to one site and is read-only apart from the three collect endpoints.
- Visitors are identified by an HMAC of IP + user agent + site ID + UTC date, truncated to 16 hex characters. It rotates daily, is not reversible, and differs per site. The raw IP is used for geolocation and this hash, then discarded.
- Sending events from a server requires passing the visitor's `ip` and `ua` so the event joins the right session. Omitting them is valid but creates a standalone session.
- Custom event limits: name up to 128 chars (a leading `_` is reserved), up to 20 props, string prop values up to 256 chars, revenue any finite number.
- Collect rate limit: burst of 120 events, sustained 20 events/second, per site, shared between pageviews and custom events.
- `timestamp` on collect requests must be within the last 2 years and no more than 5 minutes in the future.

## Docs

- [Overview and quickstart](https://thunderstats.com/docs/): what ThunderStats is, the one-line install, and how visitor identification works without cookies.
- [Install the tracker](https://thunderstats.com/docs/installation): the script tag, auto-tracking attributes (`data-track-clicks`, `data-track-scroll`, `data-track-404`), Content Security Policy requirements, WordPress, and verification steps.
- [Custom events](https://thunderstats.com/docs/events): `thunderstats.track(name, props, revenue)` from the browser, the equivalent server-side call, field limits, and how to read events back.
- [Goals and funnels](https://thunderstats.com/docs/goals-funnels): page goals with wildcard path matching, event goals matched by name, and multi-step funnels mixing both.
- [HTTP API reference](https://thunderstats.com/docs/api): authentication, `POST /api/collect`, `POST /api/collect/batch`, `POST /api/collect/event`, the read endpoints, period selection, filtering syntax, rate limits and error codes.

## Optional

- [Privacy policy](https://thunderstats.com/privacy): exactly what is and is not collected, retention windows, and sub-processors.
- [Full documentation as one file](https://thunderstats.com/llms-full.txt): every page above inlined as plain markdown, for fetching the whole corpus in a single request.