Skip to main content

Events API reference

The Plausible Events API can be used to record pageviews and custom events. This is useful when tracking Android or iOS mobile apps, or for server side tracking.

In most cases we recommend installing Plausible through our provided script or one of the many integration packages listed here. However, if there's no easy way for you to integrate with Plausible, you can still do so by sending events directly to our API.

Unique visitor tracking​

Important! Special care should be taken with two key headers which are used for unique visitor counting:

  1. The User-Agent header
  2. The X-Forwarded-For header

If these headers are not sent exactly as required, unique visitor counting will not work as intended. Please refer to the Request headers section below for more in-depth documentation on each header separately.

Endpoints​

POST /api/event​

Records a pageview or custom event. When using this endpoint, it's crucial to send the HTTP headers correctly, since these are used for unique user counting.

Try it yourself
curl -i -X POST https://plausible.io/api/event \
  -H 'User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/85.0.4183.121 Safari/537.36 OPR/71.0.3770.284' \
  -H 'X-Forwarded-For: 127.0.0.1' \
  -H 'Content-Type: application/json' \
  --data '{"name":"pageview","url":"http://dummy.site","domain":"dummy.site"}'
Response 202 Accepted
{}

Request headers​

User-Agent REQUIRED

The raw value of User-Agent is used to calculate the user_id which identifies a unique visitor in Plausible.

User-Agent is also used to populate the Devices report in your Plausible dashboard. The device data is derived from the open source database device-detector. If your User-Agent is not showing up in your dashboard, it's probably because it is not recognized as one in the device-detector database.

X-Forwarded-For REQUIRED

Used to get the IP address of the client. The IP address is used to calculate the user_id which identifies a unique visitor in Plausible. The raw value is anonymized and not stored. If the header contains a comma-separated list (as it should if the request is sent through a chain of proxies), then the first valid IP address from the list is used.

More information can be found on MDN docs.

Content-Type REQUIRED

Must be either application/json or text/plain. In case of text/plain, the request body is still interpreted as JSON.

Request body JSON parameters​

domain REQUIRED

Domain name of the site in Plausible

note

This is the domain name you used when you added your site to your Plausible account. It doesn't need to be an actual domain name, so when adding your mobile app to Plausible, you could insert the mobile app name in the domain name field

name REQUIRED

Name of the event. Can specify pageview which is a special type of event in Plausible. All other names will be treated as custom events.

url REQUIRED

URL of the page where the event was triggered. If the URL contains UTM parameters, they will be extracted and stored. When using the script, this is set to window.location.href.

The maximum size of the URL, excluding the domain and the query string, is 2,000 characters. Additionally, URLs using the data URI scheme are not supported by the API.

note

The URL parameter will feel strange in a mobile app but you can manufacture something that looks like a web URL. If you name your mobile app screens like page URLs, Plausible will know how to handle it. So for example, on your login screen you could send something like:

event: pageview
url: app://localhost/login

The pathname (/login) is what will be shown as the page value in the Plausible dashboard.

referrer optional

Referrer for this event. When using the standard tracker script, this is set to document.referrer

Referrer values are processed heavily for better usability. Consider referrer URLS like m.facebook.com/some-path and facebook.com/some-other-path. It's intuitive to think of both of these as coming from a single source: Facebook. In the first example the referrer value would be split into visit:source == Facebook and visit:referrer == m.facebook.com/some-path.

Plausible uses the open source referer-parser database to parse referrers and assign these source categories.

When no match has been found, the value of the referrer field will be parsed as an URL. The hostname will be used as the visit:source and the full URL as the visit:referrer. So if you send https://some.domain.com/example-path, it will be parsed as follows: visit:source == some.domain.com visit:referrer == some.domain.com/example-path

props optional

Custom properties for the event. These can be attached to both pageview and custom events. To learn more about using custom properties, you can check out these two links:

The value corresponding to the props key in the request body is expected to be a JSON object. For example, if you're using the text/plain content type, your request body might look like this:

'{"name":"pageview","url":"http://dummy.site","domain":"dummy.site","props":{"author":"John Doe","logged_in":"false"}}'
note

You can can use GET https://plausible.io/api/health endpoint to monitor the status of our API