View Source API Reference Plausible v0.0.1
Modules
A simple DNS server that responds to TXT queries with fixed sample values.
Build-related macros
Pattern match assertions wrapper macro extending it with checks expressed directly within the pattern.
Clickhouse access with async inserts enabled
Primary persistent Audit Entry interface
Persistent Audit Entry schema
LiveView on_mount callback to provide audit context
Equips Ecto.Repo with audited insert/update/delete variants. This module will potentially augment db operations with transaction wrappers.
Functions for user authentication context.
Schema for email activation codes.
API for verifying emails.
API for SSO.
Once SSO integration is initiated, it's possible to start allow-listing domains for it, in parallel with finalizing the setup on IdP's end.
SSO domain ownership verification chain
Background service validating SSO domains ownership
API for SSO domains.
SSO Identity struct.
Instance of particular SSO integration for a given team.
SAML SSO can be configured in two ways - by either providing IdP metadata XML or inputting required data one by one.
TOTP auth context
Defines an Ecto type so Cloak.Ecto can encrypt/decrypt a binary field.
Schema for TOTP recovery codes.
Provides a vault that will be used to encrypt/decrypt the TOTP secrets of users who enable it.
Schema for storing user session data.
Functions for interacting with user sessions.
This module mocks API requests made to Paddle in the :dev environment.
Module for conveniently handling subscriptions in the :dev environment.
Ecto type representing a feature. Features are cast and stored in the
database as strings and loaded as modules, for example: "props" is loaded
as Plausible.Billing.Feature.Props.
Ecto type representing a limit, that can be either a number or unlimited.
Unlimited is dumped to the database as -1 and loaded as :unlimited to
keep compatibility with the rest of the codebase.
This module provides an interface for managing features, e.g. Revenue Goals, Funnels and Custom Properties.
Unlike other feature modules, this one only exists to make feature gating settings views more convenient. Other than that, it's not even considered a feature on its own. The real access to "Teams" is controlled by the team member limit.
This module provides functions to work with plans usage and limits.
The subscription statuses are stored in Paddle. They can only be changed through Paddle webhooks, which always send the current subscription status via the payload.
Caching interface specific for Plausible. Usage
Interface for the underlying cache implementation. Currently: ConCache
A periodic cache warmer.
Helper function for working with Ecto changesets
Provides the core functions to retrieve and manage the CLDR data that supports formatting and localisation.
Parses HTTP Accept-Language header values as defined in
rfc2616.
Backend module that provides functions to define new locales and display human-readable locale names for presentation purposes.
A backend module for Money.
Formats numbers and currencies based upon CLDR's decimal formats specification.
Implements cardinal plural rules for numbers.
Functions to manage the collection of number patterns defined in Cldr.
Implements ordinal plural rules for numbers.
Implements plural rules for ranges
Transliteration for digits and separators.
Functions to implement the number system rule-based-number-format rules of CLDR.
Functions to implement the ordinal rule-based-number-format rules of CLDR.
Functions to implement the spellout rule-based-number-format rules of CLDR.
Event schema for when NumericIDs migration is complete
Schema for storing location id <-> translation mappings in ClickHouse
Session schema for when NumericIDs migration is complete
Custom type to cast Bool as UInt8
Contextual interface for consolidated views, each implemented as Site object serving as pointers to team's regular sites.
Caching layer for consolidated views.
Custom plan price estimation
Generic behaviour for CS resources
This module defines the setup for tests requiring access to the application's data layer.
Base module for coordinated Clickhouse data migrations run via remote shell or otherwise (TBD).
Creates dictionaries and functions to calculate acquisition channel in ClickHouse
Backfill and sync all teams related entities.
!!!WARNING!!!: This script is used in migrations. Please take special care when altering it.
Backfill Plausible.Site.TrackerScriptConfiguration for all sites.
A snapshot of the Plausible.Site.TrackerScriptConfiguration schema from May 2025.
Clean up referrer_source entries for demo site with
Direct / None for value populated by dogfooding
Plausible stats.
Ecto.Repo for Clickhouse data migrations, to be started manually, outside of the main application supervision tree.
ClickHouse locations data migration for storing location names in ClickHouse.
Numeric IDs migration, SQL files available at: priv/data_migrations/NumericIDs/sql
Populates event session columns with data from sessions table.
Ecto.Repo for Posrtgres data migrations, to be started manually, outside of the main application supervision tree.
Migration to update tracker script configuration IDs to use the new prefixed format.
!!!WARNING!!!: This script is used in migrations. Please take special care when altering it.
A snapshot of the Plausible.Imported.SiteImport schema from April 2024.
!!!WARNING!!!: This script is used in migrations. Please take special care when altering it.
Thin wrapper around :inet_res.lookup/5.
To use, call Plausible.DnsLookup.impl().lookup/5,
this allows for mocking DNS lookups in tests.
Behaviour module for DNS lookup operations.
Custom type for event name. Accepts Strings and Integers and stores them as String. Returns cast error if any other type is provided. Accepting integers is important for 404 tracking.
Ensures that the regex is compiled on load
Custom column type for nanoid strings
Base module for nanoid string types
Custom column type for tracker script configuration nanoid strings with pa- prefix
Contains functions to export data for events and sessions as Zip archives.
File helpers for Plausible.
A funnel is a marketing term used to capture and describe the journey that users go through, from initial step to conversion. A funnel consists of several steps (here: 2..8).
Compile-time convenience constants for funnel characteristics.
This module defines the database schema for a single Funnel step.
See: Plausible.Funnel for more information.
This module implements contextual Funnel interface, allowing listing, creating and deleting funnel definitions.
This module provides an API for fetching IP geolocation.
Currency specific functions for revenue goals
This module contains logic for special goals
API to Google services.
Mock of API to Google services.
API for Google Analytics 4.
HTTP client implementation for Google Analytics 4 API.
Report request struct for Google Analytics 4 API
HTTP Client built on top of Finch.
HelpScout callback API logic.
Provides a vault that will be used to encrypt/decrypt the stored HelpScout API access tokens.
Common helpers for JSON handling
A dedicated repo for import related mutations
Context for managing site statistics imports.
This GenServer inserts records into Clickhouse imported_* tables. Multiple buffers are
automatically created for each table. Records are flushed when the table buffer reaches the
maximum size, defined by max_buffer_size/0.
CSV importer from either S3 for which it uses ClickHouse s3 table function or from local storage for which it uses input function.
Import implementation for Google Analytics 4.
Definitions of import sources.
Behaviour that should be implemented for each import source.
Stub import implementation.
Site import schema.
Import implementation for Universal Analytics.
Write-centric Clickhouse access interface
This module is responsible for figuring out acquisition channel from event referrer_source.
This is instrumentation necessary for keeping track of per-domain internal metrics. Due to metric labels cardinality (domain x metric_name), these statistics are not suitable for prometheus/grafana exposure, hence an internal storage is used.
A buffer aggregating counters for internal metrics, within 10 seconds time buckets.
Clickhouse schema for storing ingest counter metrics
Subscribes to telemetry events emitted by Plausible.Ingestion.Event.
Every time a request derived event is either dispatched to clickhouse or dropped,
a telemetry event is emitted respectively. That event is captured here,
its metadata is extracted and sent for internal stats aggregation via
Counters.Buffer interface.
This module exposes the build_and_buffer/1 function capable of
turning %Plausible.Ingestion.Request{} into a series of events that in turn
are uniformly either buffered in batches (to Clickhouse) or dropped
(e.g. due to spam blocklist) from the processing pipeline.
Revenue specific functions for the ingestion scope
Registers and persists sessions and events.
Embedded implementation of session and event persistence.
Embedded implementation with async relay to remote.
Remote implementation of session and event persistence.
Sets up telemetry for remote calls to persistor via Finch.Telemetry events.
The %Plausible.Ingestion.Request{} struct stores all needed fields to create an event downstream. Pre-eliminary validation is made to detect user errors early.
Revenue specific functions for the ingestion scope
Resolves the source dimension from a combination of referer header and either utm_source, source, or ref query parameter.
This top level module is the middle ground between pre-installation site scans and verification of whether Plausible has been installed correctly.
Req options for browserless.io requests
Behaviour to be implemented by a specific installation support check.
Takes two arguments
Calls the browserless.io service (local instance can be spawned with make browserless)
and runs detector script via the function API.
Checks if site domain has an A record.
If not, checks if prepending www. helps,
because we have specifically requested customers to register the domain with www. prefix.
If not, skips all further checks.
Calls the browserless.io service (local instance can be spawned with make browserless)
and runs verifier script via the function API.
If the output of previous checks can not be interpreted as successful, as a last resort, we try to bust the cache of the site under test by adding a query parameter to the URL, and running VerifyInstallation again.
Checks that are performed pre-installation, providing recommended installation methods and whether v1 is used on the site.
Module responsible for translating diagnostics to user-friendly errors and recommendations.
Diagnostics interpretation result.
The state to be shared across check during site installation support.
URL utilities for installation support, including cache busting functionality.
Checks that are performed during tracker script installation verification.
Module responsible for translating diagnostics to user-friendly errors and recommendations.
Error that has compile-time enforced checks for the attributes.
This module ensures that you cannot run Plausible Analytics Enterprise Edition without a valid license key. The software contained within the ee/ and assets/js/dashboard/ee directories are Copyright © Plausible Insights OÜ. We have made this code available solely for informational and transparency purposes. No rights are granted to use, distribute, or exploit this software in any form.
Base module for to use in Clickhouse migrations
Custom OpenTelemetry sampler implementation that ignores particular traces to reduce noise. Ingestion HTTP requests and queries to Oban tables are ignored, for example.
Cursor-based pagination.
Context module for querying API capabilities
Plugins API context module for Custom Props. All high level Custom Props operations should be implemented here.
Plugins API context module for Funnels. All high level Funnel operations should be implemented here.
Plugins API context module for Goals. All high level Goal operations should be implemented here.
Plugins API context module for Shared Links. All high level Shared Links operations should be implemented here.
Ecto schema for Plugins API Tokens. Tokens are stored hashed and require a description.
Context module for Plugins API Tokens. Exposes high-level operation for token-based authentication flows.
Enforce team role to be within the declared set.
:current_team_role is assumed to be populated by PlausibleWeb.AuthPlug.
Plug for handling expired session. Must be added after AuthPlug.
Plug for restricting user access by type.
Plug ensuring user is permitted to access the team if it has SSO setup with Force SSO policy.
Custom PromEx plugin for instrumenting code within Plausible app.
"Striped" storage based on PromEx.Storage.Peep.
Context module for handling custom event props.
Deletes data from a site.
Thin wrapper around :ets.update_counter/4 and a
clean-up process to act as a rate limiter.
Custom request logger which
Helper functions for S3 exports/imports.
Module for accessing Segments.
This module contains functions that enable resolving segments in filters.
Schema for segments. Segments are saved filter combinations.
Sentry callbacks for filtering and grouping events
Serialize session processing to avoid explicit locks
Serialize session processing to avoid explicit locks
Cross-deployment transfer for :sessions cache.
Schema for Country Block List
Allows retrieving Country Rules by domain and country code
Schema for Hostnames allow list
Allows retrieving Hostname Rules by domain
Schema for IP block list
Allows retrieving IP Rules by domain and IP
Schema for Pages block list
Allows retrieving Page Rules by domain
Contextual interface for shields.
Site schema
The cache allows lookups by both domain and domain_changed_from
fields - this is to allow traffic from sites whose domains changed within a certain
grace period (see: Plausible.Site.Transfer).
Basic interface for domain changes.
Thin wrapper around Plausible.RateLimit for gate keeping domain-specific events
during the ingestion phase. When the site is allowed, gate keeping
check returns :allow, otherwise a :deny tagged tuple is returned
with one of the following policy markers
Embedded schema for analytics imports
A site deletion service stub.
Schema for tracker script configuration
Configuration schema for site-specific traffic change notifications.
User-specific site preferences schema
Sites context functions.
Builds aggregate results for v1 of our stats API and dashboards.
Builds breakdown results for v1 of our stats API and dashboards.
This module provides functions for comparing query periods.
Module for querying user defined 'custom properties'.
Parses a dashboard query string into %ParsedQueryParams{}. Note that
metrics and dimensions do not exist at this step yet, and are expected
to be filled in by each specific report.
Takes a %ParsedQueryParams{} struct and turns it into a query
string.
Defines a struct similar Date.Range, but with DateTime instead of Date.
A module for parsing filters used in stat queries.
Parser for legacy filter format used in Stats API v1.
Module responsible for funnel evaluation, i.e. building and executing
ClickHouse funnel query based on Plausible.Funnel definition.
Revenue specific functions for the stats scope
Stats code related to filtering and grouping by goals.
A module for building the base of an imported stats query
This module is responsible for generating SQL/Ecto expressions for dimensions, filters and metrics used in import table queries
A module for building an ecto where clause of a query out of a query for Imported tables.
Collection of functions to work with intervals.
Module for validating query parameters against JSON schema.
Module for traversing and modifying JSON schemas.
Deprecated module. See ApiQueryParser for list of valid dimensions
Module used to parse URL search params to a valid Query, used to power the API for the dashboard and v1 of our Stats API.
Calculation methods for legacy time_on_page metric. Legacy calculation methods
are used when site does not have engagement data for the requested dates.
A module listing all available metrics in Plausible.
Module used in tests to 'set' the current time.
A module used for building the Query struct from already parsed params.
Methods to manipulate Query for business logic reasons before building an ecto query.
This struct contains the (JSON-encodable) response for a query and is responsible for building it from database query results.
This module is responsible for executing a Plausible.Stats.Query and gathering results.
This module is responsible for generating SQL/Ecto expressions for dimensions and metrics used in query SELECT statement.
Various macros and common SQL fragments used in Stats code.
This module defines how special metrics like conversion_rate and
percentage are calculated.
A module for building am ecto where clause of a query out of a query.
Sampling related functions
Cache storing estimation for events ingested by a site in the past month.
This module contains logic for deciding which tables need to be queried given a query and metrics, with the purpose of reducing the number of queries and JOINs needed to perform.
Collection of functions to work with time in queries.
Module to check whether the new time on page metric is available.
Builds timeseries results for v1 of our stats API and dashboards.
Utilities for modifying stat results
Core context of teams.
This embedded schema stores information about the account locking grace period.
Guest invitation schema
Guest membership schema
Team invitation schema
Service for accepting invitations, including ownership transfers.
Service for inviting new or existing users to a sites, including ownershhip transfers.
Service for inviting new or existing users to team.
Service for rejecting invitations.
Service for removing invitations.
Service for removing a team invitation.
Abstraction for team membership(s) layout - provides a high level CRUD for setting up team memberships, including invitations. Persisting the layout, effectively takes care of delegating the operations to specialized services and sending out e-mail notifications on success, if need be. To be used in UIs allowing team memberships adjustments.
Module representing a single Team Layout element and all its state transitions, including persistence options.
Team membership schema
Service for leaving a team by member.
Service for removing a team member.
Service for updating role of a team member.
Team-specific user preferences schema
Team-wide policies.
Site transfer schema
Service for transferring sites.
Team schema
Convenience assertions for teams schema transition
Users API accounting for teams.
LazyHTML wrappers to help make assertions about HTML/DOM structures
Currently only supports post request, it's a drop-in replacement for our exvcr usage that wasn't ever needed (e.g. we had no way to re-record the cassettes anyway).
API for working with time wrapping around external libraries where necessary.
API for working with timezones wrapping around external libraries where necessary.
User context
A worker meant to be run once a day that sends out e-mail notifications to site owners assuming
Job removing expired user sessions. A grace period is applied.
Cleans deleted site data from ClickHouse asynchronously.
Periodic worker that expires domain change transition period. Old domains are frozen for a given time, so users can still access them before redeploying their scripts and integrations.
Worker for running CSV export jobs. Supports S3 and local storage. To avoid blocking the queue, a timeout of 15 minutes is enforced.
Worker for running analytics import jobs.
Worker for cleaning local files left after analytics import jobs.
This worker delivers emails for successful and failed exports
Worker for purging CDN cache for tracker scripts on cloud.
Sets sites legacy_time_on_page_cutoff depending on whether they have
sent us engagement data in the past.
Oban service sending out traffic drop/spike notifications
Internal API controller for segments.
Plug for populating conn assigns with user data on the basis of authenticated session token.
This module proxies requests to BASE_URL/avatar/:hash to www.gravatar.com/avatar/:hash.
This module exposes functions for rendering and returning plan benefits for Growth, Business, and Enterprise plans.
Common components for dasbhaord.
Components for rendering dashboard tile contents.
A banner that appears on the first dashboard launch
Component for provisioning/registration flows displaying
progress status. See PlausibleWeb.Flows for the list of
flow definitions.
Generic reusable components
Google-related components
LiveComponent for rendering a user-facing feature toggle in LiveView contexts. Instead of using form submission, this component messages itself to handle toggles.
Reusable components specific to 2FA
This module defines the test case to be used by tests that require setting up a connection.
Revenue specific functions for the API scope
Base layout component for Customer Support UI Provides common header, filter bar, and content area structure
Dedicated search component for Customer Support Handles search logic independently from other components
Component responsible for rendering search result cards for customer support resources
Shared module providing common LiveView functionality for Customer Support.
Site overview component - handles site settings and management
Site people component - handles site memberships and invitations
Site rescue zone component - handles site transfer functionality
Team audit component - handles audit log viewing
Team billing component - handles subscription and custom plans
Lists ConsolidatedViews of a team and allows creating one if none exist. Current limitation is one consolidated view per team, which always includes all sites of this team.
Team members component - handles team member management
Team overview component - handles team basic info, trial dates, notes
Team SSO component - handles SSO integration management
Team sites component - handles team sites listing
User API keys component - handles displaying user's API keys
User overview component - handles user settings, team memberships, and user management
Plausible tracking itself functions
A Plug that fetches favicon images from DuckDuckGo and returns them to the Plausible frontend.
Redirects first-launch users to registration page.
Test helper for setup blocks allowing to skip the plug processing
Static compile-time definitions for user progress flows.
See PlausibleWeb.Components.FlowProgress for rendering capabilities.
This module supplies LiveViews with currently logged in user data if session data contains a valid token.
A replacement for installation verification on Community Edition.
LiveView allowing scheduling, watching, downloading, and deleting S3 and local exports.
LiveView allowing uploading CSVs for imported tables to S3 or local storage
LiveView for the change domain flow.
Live component for the change domain form
LiveView for upgrading to a plan, or changing an existing plan.
Phoenix LiveComponent for a combobox UI element with search and selection functionality.
Default suggestion engine for the ComboBox component.
Generic components stolen from mix phx.new templates
LiveView implementation of modal component.
Pagination components for LiveViews.
Shared component base for listing team members/invitations alongside with the role dropdown.
This component is responsible for rendering the verification progress and diagnostics.
Component rendering mini-graph of site's visitors over the last 24 hours.
Customer Support home page (search)
Site coordinator LiveView for Customer Support interface.
Team coordinator LiveView for Customer Support interface.
User coordinator LiveView for Customer Support interface.
LiveView for site dashboard.
Pages breakdown component.
Flash component for LiveViews - works also when embedded within dead views
LiveView allowing listing, creating and deleting funnels.
Phoenix LiveComponent that renders a form used for setting up funnels.
Makes use of dynamically placed PlausibleWeb.Live.FunnelSettings.ComboBox components
to allow building searchable funnel definitions out of list of goals available.
Phoenix LiveComponent module that renders a list of funnels with their names and the number of steps they have.
LiveView allowing listing, creating and deleting goals.
Live view for the goal creation form
Phoenix LiveComponent module that renders a list of goals
LiveView allowing listing and deleting imports.
User assistance module around Plausible installation instructions/onboarding
Icon components for the Installation module
Instruction forms and components for the Installation module
Plain ComboBox live view wrapper, suitable for drop-in select element replacement, embeddable in dead views.
LiveView allowing listing, creating and revoking Plugins API tokens.
Live view for the goal creation form
LiveView allowing listing, allowing and disallowing custom event properties.
Live view for the custom props creation form
Phoenix LiveComponent module that renders a list of custom properties
LiveView for registration form.
LiveView for password reset form.
Live view for SSO setup and management.
This module tries to supply LiveViews with some common Sentry context (without it, there is practically none).
LiveView allowing listing, creating and deleting shared links.
Live view for the shared link creation form
LiveView for IP Addresses Shield
LiveView allowing Country Rules management
LiveView allowing hostname Rules management
LiveView for Hostnames Shield
LiveView for IP Addresses Shield
LiveView allowing IP Rules management
LiveView allowing page Rules management
LiveView for IP Addresses Shield
LiveView for sites index.
Live view for enqueuing and applying team membership adjustments.
LiveView for Team setup
LiveView coordinating the site verification process. Onboarding new sites, renders a standalone component. Embedded modal variant is available for general site settings.
Functions for managing user login preference cookies.
MJML rendered for the weekly or monthly report e-mail
Controller for Plugins API Capabilities - doesn't enforce authentication, serves as a comprehensive health check
Controller for the CustomProp resource under Plugins API
Controller for the Funnel resource under Plugins API
Controller for the Goal resource under Plugins API
Controller for the Shared Link resource under Plugins API
Controller for the Tracker Script Configuration resource under Plugins API
Common responses for Plugins API
OpenAPI schema for Capabilities
OpenAPI schema for Goal
OpenAPI schema for Custom Property disable request
OpenAPI schema for Custom Property creation request
OpenAPI schema for SharedLink list response
OpenAPI schema for an error included in a response
OpenAPI schema for Funnel
OpenAPI schema for Funnel creation request - get or creates goals along the way
OpenAPI schema for Funnel list response
OpenAPI schema for Goal
OpenAPI schema for Goal creation request
OpenAPI schema for Custom Event Goal creation request
OpenAPI schema for Pageview Goal creation request
OpenAPI schema for Custom Event Goal creation request
OpenAPI schema for Custom Event Goal object
OpenAPI schema for bulk Goal deletion request
OpenAPI schema for Goals list response
OpenAPI schema for Pageview Goal object
OpenAPI schema for Revenue Goal object
OpenAPI schema for common Goal Type
OpenAPI Link schema
OpenAPI schema for a generic 404 response
Pagination metadata OpenAPI schema
OpenAPI schema for a generic 402 response
OpenAPI schema for SharedLink object
OpenAPI schema for SharedLink creation request
OpenAPI schema for SharedLink list response
OpenAPI schema for TrackerScriptConfiguration object
OpenAPI schema for TrackerScriptConfiguration update request
OpenAPI schema for a generic 401 response
OpenAPI schema for a generic 422 response
OpenAPI specification for the Plugins API
View for rendering Capabilities on the Plugins API
View for rendering Custom Props in the Plugins API
View for rendering Plugins REST API errors
View for rendering Funnels in the Plugins API
View for rendering Goals in the Plugins API
A view capable of rendering pagination metadata included in responses containing lists of objects.
View for rendering Shared Links in the Plugins API
View for rendering Tracker Script Configuration in the Plugins API
This module defines the test case to be used by tests that require setting up a Plugins API connection.
Plug for Basic HTTP Authentication using Plugins API Tokens lookup.
Plug for authorizing access to Stats and Sites APIs.
Plug restricting access to site and shared link, when present.
A thin macro wrapper around Plug.ErrorHandler that adds Sentry context containing a readable support hash presented to the users. To be used in the user-facing APIs, so that we don't leak internal server errors.
Plug toggling registration according to selfhosted state.
Rejects bot requests by any means available.
Sets secure headers tailored for embedded content.
Plug for securing SSO routes by setting proper policies in headers.
Plug for bumping timeout on user session on every dashboard request.
Implements the strategy of retrieving client's remote IP
Fake implementation of SAML authentication interface.
Real implementation of SAML authentication interface.
This controller deals with user management via the UI in Site Settings -> People. It's important to enforce permissions in this controller.
This controller is responsible for rendering stats dashboards.
Components with teams related notices.
Helper module for building the dynamic tracker script. Used by PlausibleWeb.TrackerPlug.
Plug to serve the Plausible tracker script.
Cache for tracker script.
Functions for managing session data related to Two-Factor Authentication.
Functions for user session management.
Mix Tasks
This task is meant to replicate the behavior of cancelling a subscription. On production, this action is initiated by a Paddle webhook. Currently, only the subscription status is changed with that action.
Utility for creating Sandbox plans that are used on staging. The product of
this task is a sandbox_plans_v*.json file matching with the production
plans, just with the monthly/yearly product_id's of the sandbox plans.
This task downloads the Country Lite database from DB-IP for self-hosted or development purposes. Plausible Cloud runs a paid version of DB-IP with more detailed geolocation data.
It's often necessary to generate fake events for development and testing purposes. This Mix Task provides a quick and easy way to generate a pageview or custom event, either in your development environment or a remote Plausible instance.