Stats API reference
The Plausible Stats API offers a way to retrieve your stats programmatically. It is a read-only interface to present historical and real-time stats only. At the moment there is no API to send pageviews or custom events to our backend nor can you manage your sites through the API.
The API accepts GET requests with query parameters and returns standard HTTP responses along with a JSON-encoded body. All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.
Each request must be authenticated with an API key using the Bearer Token method. You can obtain an API key for your account by going to your user settings page plausible.io/settings.
The easiest way to explore the API is by using our Postman collection. Just define your TOKEN and SITE_ID variables and you'll have an executable API reference ready to go.
Concepts#
Querying the Plausible API will feel familiar if you have used time-series databases before. You cannot query individual records from our stats database. You can only request aggregated metrics over a certain time period.
Each request requires a site_id parameter which is the domain of your site as configured in Plausible. If you're unsure, navigate to your site
settings in Plausible and grab the value of the domain field.
Time periods#
The options are identical for each endpoint that supports configurable time periods. Each period
is relative to a date parameter. The date should follow the standard ISO-8601 format. When not specified, the date field defaults to today(site.timezone).
All time calculations on our backend are done in the timezone that the site is configured in.
12mo,6mo- Last n calendar months relative todatemonth- The calendar month thatdatefalls into30d,7d- Last n days relative todateday- Stats for the full day specified indatecustom- Provide a custom range in thedateparameter.
When using a custom range, the date parameter expects two ISO-8601 formatted dates joined with a comma as follows ?period=custom&date=2021-01-01,2021-01-31.
Stats will be returned for the whole date range inclusive of the start and end dates.
Properties#
Each pageview and custom event in our database has some predefined properties associated with it. In other analytics tools, these are often referred to as dimensions as well. Properties can be used for filtering and breaking down your stats to drill into more depth. Here's the full list of properties we collect automatically:
| Property | Example | Description |
|---|---|---|
| event:name | pageview | Name of the event triggered. pageview is a reserved event name but custom events can be named anything. |
| event:page | /blog/remove-google-analytics | Pathname of the page where the event is triggered |
| visit:source | Visit source, populated from an url query parameter tag (utm_source, source or ref) or the Referer HTTP header. | |
| visit:referrer | t.co/fzWTE9OTPt | Raw Referer header without http://, http:// or www. |
| visit:utm_medium | social | Raw value of the utm_medium query param on the entry page |
| visit:utm_source | Raw value of the utm_source query param on the entry page | |
| visit:utm_campaign | profile | Raw value of the utm_campaign query param on the entry page |
| visit:device | Desktop | Device type. Possible values are Desktop, Laptop, Tablet and Mobile |
| visit:browser | Chrome | Name of the browser vendor. Most popular ones are Chrome, Safari and Firefox |
| visit:browser_version | 88.0.4324.146 | Version number of the browser used by the visitor |
| visit:os | Mac | Name of the operating system. Most popular ones are Mac, Windows, iOS and Android. Linux distributions are reported separately |
| visit:os_version | 10.6 | Version number of the operating system used by the visitor |
| visit:country | US | ISO 3166-1 alpha-2 code of the visitor country |
Custom props#
In addition to props that are collected automatically, you can also query for custom properties.
To filter or break down by a custom property, use the key event:props:<custom_prop_name>. See example for how to use it.
Currently clients are limited to filtering or breaking down on just one custom property at a time. Custom prop filters and breakdowns cannot be combined arbitrarily. We are aware of this issue and we have plans to fix it, but we rely on our database to support some new features to fix this issue.
Filtering#
Most endpoints support a filters query parameter to drill down into your data. Currently, only simple equality filters are supported.
An equality filter can be specified with url-encoded ==. Filters can be joined together with ; which applies a logical
AND operator to the filters. Here's a filter expression combining two filters:
Endpoints#
GET /api/v1/stats/realtime/visitors#
This endpoint returns the number of current visitors on your site. A current visitor is defined as a visitor who triggered a pageview on your site in the last 5 minutes.
Parameters#
site_id REQUIRED
Domain of your site on Plausible.
GET /api/v1/stats/aggregate#
This endpoint aggregates metrics over a certain time period. If you are familiar with the Plausible dashboard, this endpoint corresponds to
the top row of stats that include Unique Visitors, Pageviews, Bounce rate and Visit duration. You can retrieve any number and combination
of these metrics in one request.
Parameters#
site_id REQUIRED
Domain of your site on Plausible.
period REQUIRED
See time periods
metrics REQUIRED
List of metrics to aggregate. Valid options are visitors, pageviews, bounce_rate and visit_duration.
compare optional
Off by default. You can specify previous_period to calculate percent difference with previous period for each metric.
filters optional
See filtering
GET /api/v1/stats/timeseries#
This endpoint provides timeseries data over a certain time period. If you are familiar with the Plausible dashboard, this endpoint corresponds to the main visitor graph.
Parameters#
site_id REQUIRED
Domain of your site on Plausible.
period REQUIRED
See time periods
filters optional
See filtering
interval optional
Choose your reporting interval. Valid options are date (always) and month (when specified period is longer than one calendar month). Defaults to
month for 6mo and 12mo, otherwise falls back to date.
GET /api/v1/stats/breakdown#
This endpoint allows you to breakdown your stats by some property. If you are familiar with SQL family databases, this endpoint corresponds to
running GROUP BY on a certain property in your stats.
Check out the properties section for a reference of all the properties you can use in this query.
This endpoint can be used to fetch data for Top sources, Top pages, Top countries and similar reports.
Parameters#
site_id REQUIRED
Domain of your site on Plausible.
property REQUIRED
Which property to break down the stats by. Valid options are listed in the properties section above.
period REQUIRED
See time periods
metrics optional
List of metrics to show for each item in breakdown. Valid options are visitors, pageviews, bounce_rate and visit_duration. If not
specified, it will default to visitors.
limit optional
Limit the number of results. Defaults to 100.
page optional
Number of the page, used to paginate results. Importantly, the page numbers start from 1 not 0.
filters optional
See filtering
Examples of common queries#
Top pages#
Let's say you want to show a similar report to the Top pages report in the Plausible UI. You can do this by calling the
/api/v1/stats/breakdown endpoint and specify event:page as the property to group by.
Number of visitors to a specific page#
Let's say you want to get the number of visitors to a specific page on your website like /order/confirmation. This can be achieved by
filtering your stats on the event:page property:
Monthly traffic from Google#
As a second example, let's imagine we want to analyze our SEO efforts for the last half year.
To graph your traffic from Google over time, you can use the timeseries endpoint with a time period 6mo and
filter expression visit:source==Google.
Breakdown custom event by custom props#
A more advanced use-case where custom events are used along with custom props. Let's say you have a Download custom event along with
a custom property called method. You can get a breakdown of download methods with the following query: