Documentation on Feasible

Installation

Mon, 01 Jan 0001 00:00:00 +0000

One script tag, on every page you want counted. No build step, no consent gate to wire up first.

<script defer src="https://app.feasible.lol/js/fs-k7m2q4x5r3n6t2v5.js"></script>

That’s 3,377 bytes gzipped - a handful more for your copy, which has your domain baked into it - and it’s deferred, so it never blocks rendering.

There are no cookies and nothing stored in the browser to identify anyone, which is why most sites won’t need a consent banner for it. Privacy and GDPR has the facts to hand your lawyer - and if you’re somewhere strict, ask them rather than us.

Integrations

Mon, 01 Jan 0001 00:00:00 +0000

The tracker is a script tag, so anything that lets you add one is supported. What follows is the list people ask about, and the one step each platform hides. The setup screen inside the product carries the same instructions with your own snippet already filled in.

WordPress

There’s a plugin, feasible.lol Analytics. It does more than paste the snippet: it serves the script and the events endpoint from your own domain on randomized paths, which is the part that survives ad blockers, and it adds the two measurements a theme can’t give you - site-search terms and 404s.

Script options

Mon, 01 Jan 0001 00:00:00 +0000

Every option is a data- attribute on the script tag, and they all work on either form of the snippet. It’s the same bundle whichever filename you load - no build flags, no feature variants to choose between, and nothing you can forget to turn on.

A value is required, not just the attribute

This trips people up, so it goes first. A bare attribute does nothing:

<script defer data-hash src="…"></script>          <!-- ignored -->
<script defer data-hash="true" src="…"></script>   <!-- on -->

Any non-empty value switches a flag on, including the string "false". To turn something off, leave the attribute out.

Proxying

Mon, 01 Jan 0001 00:00:00 +0000

Ad blockers block analytics by hostname. Serving the script and the events endpoint from your own domain is the only reliable way around that, and it costs you two proxy rules.

It’s also better for your visitors: the request goes to a host they already trust and reuses a connection their browser has open.

What to proxy

The script - a static file, cacheable. It’s served at /js/script.js, or at your site’s own /js/fs-<token>.js.
The events endpoint - POST /api/event, never cached. Proxy the whole prefix rather than the exact path, so the no-script pixel at /api/event/pixel.gif is covered too.

Caddy

example.com {
    handle /stats/js/* {
        uri strip_prefix /stats
        reverse_proxy https://app.feasible.lol {
            header_up Host app.feasible.lol
        }
    }
    handle /stats/api/event* {
        uri strip_prefix /stats
        reverse_proxy https://app.feasible.lol {
            header_up Host app.feasible.lol
        }
    }
}

Caddy sets X-Forwarded-For itself, which is all we need.

The dashboard

Mon, 01 Jan 0001 00:00:00 +0000

One screen. No report picker, no menu of saved views to get lost in. Everything is on it, and everything is filterable by clicking.

The numbers along the top

Six figures: Unique visitors, Total visits, Total pageviews, Views per visit, Bounce rate and Visit duration.

Metric definitions

Mon, 01 Jan 0001 00:00:00 +0000

Most of these are what you’d expect. The four at the bottom are the ones that surprise people, and they surprise people in every analytics product. We’d rather write them down, with the arithmetic, than let you find them in a meeting.

The metrics

Unique visitors - distinct visitor identifiers in the period. Read the section below before you use this number in a sentence containing the word “people”.
Total visits - a visit is a run of activity that ends after 30 minutes of silence. Nothing else ends it.
Total pageviews - one per page load, plus one per client-side route change.
Events - everything that isn’t a pageview: your own custom events, outbound clicks, downloads, form submissions.
Views per visit - pageviews divided by visits.
Bounce rate - the share of visits with one pageview and no other interaction. An engagement measurement isn’t an interaction; an outbound click is.
Visit duration - last activity minus first activity within a visit. A single-page visit has a duration only if the tab reported time on page.
Time on page - accumulated by the script only while the tab is both visible and focused, so a page sitting behind another window doesn’t bank hours.
Scroll depth - the furthest point reached, 1 to 100, as a percentage of the document height at the moment it was measured. Never below 1, so “never reported” and “didn’t scroll” stay distinguishable.
Exit rate - the share of visits that ended on a page, out of the visits that included it.
Conversion rate - converting visitors divided by all visitors in the period. See goals for what changes that denominator.
Group conversion rate - the same idea across a set of goals rather than one.
Total revenue, average revenue and revenue per visitor - for goals that carry money.

Six of these are on the dashboard tiles. All fifteen are available through the query API.

Goals and funnels

Mon, 01 Jan 0001 00:00:00 +0000

Goals, properties and funnels are managed in site settings and reported together at the bottom of the dashboard. The Explore tab turns the same events into an open-ended journey report. The API uses the same definitions as the screens.

All of it is in every plan. There’s no conversions add-on.

Goals

A goal is a page somebody reached, a custom event they sent, or a scroll depth reached on a page.

Custom properties

Mon, 01 Jan 0001 00:00:00 +0000

A custom property is a key and a value attached to an event, so you can break a report down by something only your application knows - a plan name, a category, a variant.

They’re in every plan, with no cap on how many you register and no “custom dimensions” allowance to buy. Send them with the tracker’s own API:

feasible('Signup', {
  props: { plan: 'yearly', referred_by: 'partner' }
})

A pageview takes them under p rather than props, which is a wart of the wire format we match for compatibility:

Excluding traffic

Mon, 01 Jan 0001 00:00:00 +0000

Two settings decide what gets counted and what it’s called. They live at /settings/sites/<your domain>/shields and /settings/sites/<your domain>/paths.

If traffic you do want is missing rather than traffic you don’t, start at installation instead.

Shields - traffic you don’t want counted

Blocked addresses

An address or a CIDR block. Checked in the ingestion tier, which is the only place the raw address still exists - after that it’s been discarded and there’s nothing left to match on.

Import and export

Mon, 01 Jan 0001 00:00:00 +0000

Bring history in from wherever you were before, and take everything out at any time. Both live at /settings/sites/<your domain>/imports.

Export

Press Prepare an export and a background job builds a ZIP containing:

the ten roll-up tables as CSV - visitors, sources, pages, entry pages, exit pages, locations, devices, browsers, operating systems and custom events;
raw_events.csv - every event, one row each.

The raw file is in every plan. Data you generated on your own site is yours, and putting the only complete copy of it behind a plan is how a customer finds out they can’t leave.

The APIs

Mon, 01 Jan 0001 00:00:00 +0000

Two APIs: one to send events, one to read numbers back. Both are HTTP and JSON, both are documented here in full, and there’s no paid tier for API access. There isn’t a plan check in the API code at all.

Sending events

POST /api/event
Content-Type: application/json

{
  "n": "pageview",
  "d": "example.com",
  "u": "https://example.com/pricing",
  "r": "https://duckduckgo.com/"
}

No authentication. The tracker runs in a browser, so a credential here would be a credential published on your website. The site is identified by d, and an event for a domain we don’t hold is dropped.

Webhooks

Mon, 01 Jan 0001 00:00:00 +0000

A webhook is us calling you when something happens, so you don’t have to poll for it. They’re managed under /api/v1/webhooks with a key carrying the webhooks:write scope.

POST /api/v1/webhooks
Authorization: Bearer feas_…

{
  "url": "https://example.com/hooks/feasible",
  "event_types": ["site.created", "traffic.spike"]
}

The response carries the signing secret - whsec_ followed by 43 characters - and that’s the only time you’ll see it. Listing or fetching a webhook never returns it. An empty event_types means every type.

The MCP server

Mon, 01 Jan 0001 00:00:00 +0000

There’s a Model Context Protocol server built in, so an AI assistant can read your analytics and ask follow-up questions without anybody writing an integration.

It’s the same query engine the dashboard uses, behind the same API keys and the same rate limits. It’s in every plan and every build, hosted or self-hosted.

Connecting over HTTP

The endpoint is POST /mcp, streamable HTTP, protocol version 2025-06-18. Authenticate with Authorization: Bearer …, carrying either an API key or an OAuth access token.

SDKs and plugins

Mon, 01 Jan 0001 00:00:00 +0000

Five server-side SDKs, a browser loader, a WordPress plugin, a Tag Manager template and a Looker Studio connector.

The source for every one of them is in the product’s repository under ecosystem/, each with its own README and its own tests. If your package manager doesn’t have one yet, that’s where to get it.

The server-side SDKs

They exist for events that happen away from a browser: a payment webhook, a background job, an offline conversion, an API-only product with no pages at all.

Self-hosting

Mon, 01 Jan 0001 00:00:00 +0000

One binary and one directory. No Docker, no external database, no queue, and no feature that only exists in the hosted version.

The software is AGPL-3.0-or-later. You can run, modify and self-host it freely. If you offer it to others as a network service, you have to make your source available to those users.

./feasible db migrate
./feasible serve

That’s the whole deployment.

serve runs the dashboard, the API, the tracker and ingestion in one process, which is what almost every self-hoster should run. The other commands are ingest, db backup, rollup, seed, api-key, mcp, billing, comp and account.

Privacy and GDPR

Mon, 01 Jan 0001 00:00:00 +0000

The short version: no cookies, no persistent identifier, no cross-site tracking, no data sold or used for advertising, and no IP address ever written to disk.

This is the technical page. The argument is on privacy-friendly analytics, the legal one is the privacy and data policy, and the processor contract is the data processing addendum.

The visitor identifier is pseudonymous, not anonymous

To tell a returning visitor from a new one within a single day, we compute one number: