PilotFox developer documentation
Everything a developer needs to send data to PilotFox, read it back over the REST API or MCP, and run PilotFox on their own servers.
PilotFox is cookieless web and product analytics. A small script on your website sends pageviews and events; PilotFox works out visitors and sessions on its server, adds location, device and traffic source, and turns the stored events into reports: traffic, sessions and users, goals, funnels, journeys, retention, session replays, web vitals, errors, bots, revenue, affiliates and Google Search Console.
You can use it at pilotfox.app or run it on your own server. These docs cover both, and say where a self-hosted instance differs.
Where to start
Install the script
Site owners: from sign-up to the first tracked visit, then events, identify and single-page apps.
Use the API or MCP
Developers: read reports and manage sites with an API key, send events from your server, connect an AI assistant.
Run your own instance
Operators: the services PilotFox runs on, Docker Compose, configuration, backups and upgrades.
How these docs are organised
| Section | What it covers |
|---|---|
| Getting started | Organizations, sites, members and roles; the quickstart; how each metric is defined. |
| Tracking | The tracking script: installing it, custom events and identify, single-page apps, serving it from your own domain, opt-out and session replay. |
| REST API | Authentication, permissions, query parameters, pagination, errors, rate limits and the generated API reference. |
| Server-side ingest | Sending events and identifying users from your own server with an API key. |
| MCP server | Letting AI assistants read your analytics over the Model Context Protocol. |
| Revenue, Affiliates, Search Console, Notifications | The product features that connect to other services. |
| Privacy | How visitors are counted without cookies, what is stored and never stored, access and deletion. |
| Self-hosting | Running PilotFox on your own server. |
| FAQ | Short answers to common questions. |
Conventions
These placeholders appear throughout the docs:
| Placeholder | Meaning |
|---|---|
https://pilotfox.app | The PilotFox instance. On a self-hosted instance, use its own address (its PUBLIC_URL) everywhere instead. |
SITE_ID | A site's public id: 16 lowercase letters and digits, the data-site value of its script tag. It is also the siteId in API paths such as /api/v1/sites/SITE_ID/.... Site settings → Tracking code shows it in the tag. |
$PILOTFOX_API_KEY | An organization API key, read from an environment variable. See Authentication. API keys belong on your server only, never in a web page. |
For example, to download a site's raw events for September with an API key that has the exports:read and
sessions:read permissions:
curl -H "Authorization: Bearer $PILOTFOX_API_KEY" \
"https://pilotfox.app/api/v1/sites/SITE_ID/export?format=jsonl&start=2026-09-01&end=2026-09-30" \
-o events.jsonl