Skip to main content

​
Endpoint

POST /api/event
The Event Ingestion endpoint accepts pageview and custom events from your website or application. This is the primary endpoint used by the Plausible Analytics tracking script.

​
Authentication

No authentication required. Events are associated with sites based on the domain or url parameter.

​
Request Headers

​
User-Agent
string
The user agent string from the visitor’s browser. Used for browser and OS detection.
​
X-Plausible-IP-Type
string
Optional IP classification header. Values: dc_ip, threat_ip, anonymous_vpn_ip

​
Request Body

​
n
string
required
Event name. Also accepts name as an alternative field. Maximum length: 120 characters.Note: The event name engagement is reserved for internal use and cannot be used as a custom event.
​
u
string
required
Full URL of the page. Also accepts url as an alternative field. Maximum length: 2000 bytes.The URL scheme cannot be data.
​
d
string
Domain name. Also accepts domain as an alternative field. Can be a comma-separated list for tracking multiple domains.If not provided, extracted from the url parameter.
​
r
string
Referrer URL. Also accepts referrer as an alternative field. Maximum length: 2000 bytes.
​
p
object
Custom properties (props) for the event. Also accepts props, m, or meta as alternative fields.
  • Maximum 30 properties per event
  • Keys: maximum 300 bytes
  • Values: maximum 2000 bytes
  • Keys and values must be strings (lists and maps are filtered out)
​
h
integer
Hash mode. Also accepts hashMode as an alternative field.When set to 1, includes the URL fragment in the pathname.
​
i
boolean
default:"true"
Interactive flag. Also accepts interactive as an alternative field.Set to false to mark the event as non-interactive (won’t affect bounce rate).Note: Some system events (like pageview) always have interactive set to true.
​
v
integer
Tracker script version number. Used internally for telemetry.
​
sd
integer
Scroll depth percentage (0-100). Required for engagement events.Values above 100 are clamped to 100.
​
e
integer
Engagement time in milliseconds. Required for engagement events.Must be less than 30 days (2,592,000,000 ms).

​
Response

​
status
integer
HTTP status code:
  • 202 - Event accepted and buffered successfully
  • 400 - Invalid request (see error response)

​
Success Response

HTTP/1.1 202 Accepted

ok

​
Partial Success Response

When some events are dropped but the request is otherwise valid: 
HTTP/1.1 202 Accepted
X-Plausible-Dropped: 1

ok
​
X-Plausible-Dropped
string
Number of events dropped during processing. Present when events were filtered out due to spam, bots, shields, etc.

​
Error Response

{
  "errors": {
    "url": ["is required"],
    "event_name": ["can't be blank"]
  }
}

​
Drop Reasons

Events may be dropped for the following reasons:
  • :bot - Detected as bot traffic (including Headless Chrome)
  • :spam_referrer - Referrer matches spam blocklist
  • :dc_ip - Datacenter IP address
  • :threat_ip - Threat IP address
  • :site_ip_blocklist - Blocked by site’s IP shield rules
  • :site_country_blocklist - Blocked by site’s country shield rules
  • :site_page_blocklist - Blocked by site’s page shield rules
  • :site_hostname_allowlist - Not allowed by site’s hostname allowlist
  • :verification_agent - Internal verification agent
  • :invalid - Failed validation
curl -X POST https://plausible.io/api/event \
  -H "User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36" \
  -H "Content-Type: application/json" \
  -d '{
    "n": "pageview",
    "u": "https://example.com/blog",
    "d": "example.com",
    "r": "https://google.com"
  }'

​
Custom Event Example

curl -X POST https://plausible.io/api/event \
  -H "User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36" \
  -H "Content-Type: application/json" \
  -d '{
    "n": "Signup",
    "u": "https://example.com/signup",
    "d": "example.com",
    "p": {
      "plan": "premium",
      "method": "google"
    }
  }'

​
Notes

  • Events are processed asynchronously and buffered before being written to ClickHouse
  • The endpoint returns 202 Accepted immediately after validation, before the event is persisted
  • User IDs are generated based on IP address, user agent, domain, and rotating salts
  • Geolocation is performed based on the visitor’s IP address
  • Sessions are tracked automatically based on user ID and timestamp

Build docs developers (and LLMs) love

Get started for freeTalk to us