Skip to main content

​
Overview

The Plausible Events API allows you to track events from server-side applications, mobile apps, or any environment where the JavaScript tracker cannot be used. Events are sent as HTTP POST requests to the Plausible API endpoint.

​
API Endpoint

All events are sent to: 
POST https://plausible.io/api/event
For self-hosted instances, replace the domain with your Plausible server URL.

​
Authentication

The Events API does not require authentication for basic event tracking. Events are associated with your site based on the domain field in the request payload.
Do not confuse the Events API (for tracking) with the Stats API (for retrieving analytics data). The Stats API requires authentication via API keys.

​
Request Format

Events are sent as JSON POST requests with the following structure:

​
Headers

Content-Type: application/json
User-Agent: Mozilla/5.0 (compatible; YourApp/1.0)
X-Forwarded-For: 192.168.1.1
The User-Agent header is used to detect the visitor’s browser and operating system. The X-Forwarded-For header can be used to pass the visitor’s IP address when making requests from a server.

​
Payload Structure

The JSON payload contains event data with shortened field names for efficiency: 
{
  "n": "pageview",
  "u": "https://example.com/blog/post",
  "d": "example.com",
  "r": "https://google.com",
  "v": "1.0.0"
}

​
Payload Fields

​
n
string
required
Event name. Use "pageview" for pageviews or any custom event name.
​
u
string
required
URL of the page where the event occurred. Must include protocol and domain.
​
d
string
required
Domain of your site as configured in Plausible.
​
r
string
Referrer URL. The page that linked to the current page.
​
v
string
Tracker script version for debugging purposes.
​
p
object
Custom properties for the event. See custom properties documentation.
"p": {
  "author": "John Doe",
  "category": "Technology"
}
​
i
boolean
default:"true"
Whether the event is interactive. Non-interactive events don’t affect bounce rate.
"i": false
​
$
object
Revenue information for ecommerce tracking. See revenue tracking.
"$": {
  "amount": "29.99",
  "currency": "USD"
}
​
h
number
Set to 1 for hash-based routing. Includes the URL hash in pageview tracking.

​
Response Codes

The API returns the following HTTP status codes:
Status CodeDescription
202Event accepted and queued for processing
400Bad request - invalid payload or validation error
429Too many requests - rate limit exceeded

​
Success Response

HTTP/1.1 202 Accepted
Content-Type: text/plain

ok

​
Error Response

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "errors": {
    "domain": ["can't be blank"],
    "name": ["can't be blank"]
  }
}

​
Examples

​
Pageview Event

Track a simple pageview: 
curl -X POST https://plausible.io/api/event \
  -H 'Content-Type: application/json' \
  -H 'User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36' \
  -d '{
    "n": "pageview",
    "u": "https://example.com/blog",
    "d": "example.com",
    "r": "https://google.com"
  }'

​
Custom Event with Properties

Track a custom event with additional metadata: 
{
  "n": "Signup",
  "u": "https://example.com/signup",
  "d": "example.com",
  "p": {
    "plan": "premium",
    "method": "google"
  }
}

​
Revenue Tracking

Track an event with revenue information: 
{
  "n": "Purchase",
  "u": "https://example.com/checkout/success",
  "d": "example.com",
  "p": {
    "product": "Pro Plan"
  },
  "$": {
    "amount": "29.99",
    "currency": "USD"
  }
}
Revenue tracking requires the appropriate plan. See ecommerce revenue tracking for more details.

​
Non-Interactive Event

Track an event that shouldn’t affect bounce rate: 
{
  "n": "Video Autoplay",
  "u": "https://example.com/video",
  "d": "example.com",
  "i": false
}

​
Event Processing

When an event is received, Plausible processes it through an ingestion pipeline that:
  1. Validates the request payload
  2. Checks for bot traffic and spam referrers
  3. Applies site-specific filters (IP blocklist, country blocklist, etc.)
  4. Extracts geolocation data from the IP address
  5. Parses the User-Agent for browser and OS information
  6. Associates the event with a visitor session
  7. Buffers the event for batch insertion into the database

​
Event Validation

Events are validated against the following rules:
  • domain must match a configured site in your Plausible account
  • name (event name) cannot be blank
  • url must be a valid URL with protocol
  • Custom property keys and values must be strings
  • Revenue amount must be numeric
  • Revenue currency must be a valid ISO 4217 currency code

​
Drop Reasons

Events may be dropped for various reasons:
  • Bot traffic detected via User-Agent
  • Spam referrer blocklist match
  • Data center or threat IP address
  • Site-specific shield rules (IP blocklist, country blocklist, page blocklist)
  • Hostname not in site’s allowlist
  • Invalid event data

​
Rate Limits

The Events API has rate limits to prevent abuse:
  • 600 events per minute per domain
  • Burst capacity of 120 events
Exceeding rate limits will result in HTTP 429 responses. Implement exponential backoff for retries.

​
Best Practices

1

Set Accurate User-Agent

Always send a realistic User-Agent header to ensure accurate browser and OS tracking.
2

Forward Client IP

Use X-Forwarded-For header to pass the actual visitor IP when making server-side requests.
3

Handle Errors Gracefully

Check response status codes and handle validation errors appropriately.
4

Don't Track Sensitive Data

Never send personally identifiable information (PII) in URLs or custom properties.
5

Use Async Requests

Send events asynchronously to avoid blocking your application.

​
Next Steps

Custom Events

Learn about custom event tracking

Custom Properties

Add metadata to your events

Build docs developers (and LLMs) love

Get started for freeTalk to us