Events API reference

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

In most cases we recommend installing Plausible via our provided script or one of the many interation 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.

Endpoints#

POST /api/event#

Records a pageview or custom event. When using this endpoint, make sure you're sending the correct headers:

User-agent is used to determine the user's device
X-Forwarded-For is used to determine the client's IP address
Content-Type must be either application/json or text/plain

In combination, these two values are used for unique user counting. If you have problems with uniqueness counting, please make sure you are sending User Agent and X-Forwarded-For correctly.

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","width":1666}'
Response 202 Accepted
{}

Post body JSON parameters#


domain REQUIRED

Domain name of the site in Plausible


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


referrer optional

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


screen_width optional

Width of the screen. When using the script, this is set to window.innerWidth


props optional

Custom properties for the event. See: https://plausible.io/docs/custom-event-goals#using-custom-props