How to get KPIs and metrics from the Plausible API

Plausible is an easy to use and privacy-friendly website analytics software to track your website visitor, page view analytics and custom events and has a flexible API to get timeseries data. You can find their documentation here: Plausible's API.

Contents

• Authentication
• Endpoint
• How to get page view metrics from Plausible
• How to get event metrics from Plausible
• Plausible API Results

Authentication

For authentication you provide a Bearer token, which you can create for your account under the Account Settings > API Keys in Plausible.

Endpoint

To get statistical metrics like page views or events from their API you can use the stats endpoint. For aggregations the timeseries sub-endpoint is the most useful.

• https://plausible.io/api/v1/stats/timeseries

How to get page view metrics from Plausible

For these requests the site_id parameter is domain of your site in plausible, e.g. example.com.

https://plausible.io/api/v1/stats/timeseries
  // Replace this with the id of the site
  ?site_id=SITE_ID
  // See options below
  &interval=day
  &metrics=pageviews
  // Specify date range as follows
  &period=custom
  &date=2024-01-01,2024-01-31

Options for parameter:

• metrics: Provide a comma separated list any of these:
  • visitors
  • visits
  • pageviews
  • views_per_visit
  • bounce_rate
  • visit_duration
• interval: The smallest interval supported by Plausible is day
• period and date: To request a certain date period, specify the period as custom and provide the from and to date as a comma seperated pair

How to get event metrics from Plausible

In addition to the site_id parameter described above, you can specify the filter parameter to get the metrics for a specific event. First you setup custom event (Plausible uses the name Goals) in your site settings. Then to filter by a specific event you specify this parameter as event:goal==EVENT_DISPLAY_NAME. Note the EVENT_DISPLAY_NAME is the Display Name, not the Event Name.

https://plausible.io/api/v1/stats/timeseries
  // Replace this with the id of the site
  ?site_id=SITE_ID
  &filter=event:goal==EVENT_DISPLAY_NAME
  // See options below
  &interval=day
  &metrics=pageviews
  // Specify date range as follows
  &period=custom
  &date=2024-01-01,2024-01-31

The other options for parameter are as above.

Plausible API Results

The endpoint will return the following data aggregated by day.

{
  "results": [
    {
      "date": "2020-08-01",
      "visitors": 36085
    },
    ...
  ]
}

As of September 2024 this endpoint does not have any pagination and returns all matching results for this query.