Start free Dashboard
Browse docs

Events API

Updated

On this page
  1. Fields
  2. Responses
  3. Server-side notes

Anything that speaks Plausible's Events API works. Post to /api/event:

curl -X POST https://stats.example.com/api/event \
  -H "User-Agent: Mozilla/5.0 …" \
  -H "Accept-Language: en-US,en;q=0.9" \
  -H "X-Forwarded-For: 203.0.113.7" \
  -H "Content-Type: application/json" \
  -d '{"n":"pageview","u":"https://example.com/pricing","d":"example.com","r":null,"w":1280}'

Fields

Field Required Meaning
n yes Event name. pageview for pageviews
u yes Full URL, http or https
d yes Site domain as added in Tidemark
r no Referrer URL
w no Window width in pixels, used for the device type
p no Properties object. See limits
h no 1 to include the URL fragment in the path

Long names are also accepted: name, url, domain, props.

Responses

Status Body Meaning
202 ok Accepted. Also returned when the event was dropped by a bot filter or shield
400 message Missing name, URL or domain, or an invalid URL
404 Unknown site The domain isn't a site in Tidemark

Server-side notes

The endpoint is cross-origin by design. Visitor identity, location and device come from the request, so a server-side call identifies as your server unless you forward the visitor's User-Agent and X-Forwarded-For.

The request body may be sent as text/plain, which is what the script does to avoid a CORS preflight.

Because of bot and spam filtering, a server-side call is left out (and answered with 202 ok as usual) when it has no Accept-Language header, uses a bot or script user agent, or forwards an address from a cloud provider. Forward the visitor's own User-Agent, Accept-Language and X-Forwarded-For, as in the example above. While testing from a server you can turn the filter off for the site under Site settings → Tracking.

Was this helpful?

Ready to try Tidemark?

Free plan, no credit card. No cookies, no footprints.

Start free