How do I send a referrer with a server-side Plausible event?

Definition: A server-side Plausible event carries its referral URL in the optional referrer field of the JSON request body sent to POST /api/event. The request also supplies the event name, page URL, site domain, and visitor information through HTTP headers.

Key facts

• As of 17 October 2026, Plausible's Events API reference documents referrer as optional; the standard tracker fills it from document.referrer.
• Plausible's data policy identifies the website domain, IP address and user agent as inputs to its daily visitor identifier.
• Plausible's traffic sources documentation states that referral sources are counted when they start a new session, and the source bringing the visitor to the site is retained when the visitor returns from a payment provider.

Where does the referrer go in the request?

The Events API reference places referrer alongside the required name, url and domain body fields. This adapted payload uses the documentation's example site and example referral URL:

{
  "name": "pageview",
  "url": "http://dummy.site",
  "domain": "dummy.site",
  "referrer": "https://some.domain.com/example-path"
}

The domain value identifies the site added to the Plausible account. The url value identifies the page where the event occurs. Its hostname participates in visitor recognition, and any UTM parameters, which label campaign traffic, are extracted and stored. The event name pageview records a pageview; other names are treated as custom events.

Plausible processes referral URLs into reporting values. The same documentation gives https://some.domain.com/example-path as an unmatched referrer example: its source becomes some.domain.com, and its reported referrer becomes some.domain.com/example-path. Recognized sources are categorized using the referer-parser database.

Which headers does a server-side request need?

The request headers documentation requires User-Agent and Content-Type. The user agent is the client software's identifying string; Plausible uses its raw value for visitor recognition and derives browser, operating system and device information from it. A server-side implementation forwards the visitor's user agent.

Content-Type accepts application/json or text/plain; the body is interpreted as JSON in either case. Although X-Forwarded-For is marked optional overall, Plausible instructs backend servers and proxies to set it to the client's actual IP address. Without it, Plausible uses the sender's remote IP address.

For a proxy chain containing comma-separated addresses, Plausible uses the first valid IP address. Sending a server, hosting provider or CDN address instead of the visitor's address causes bot filtering to drop the event.

How can a dropped event be checked?

Plausible's debugging documentation states that the API returns HTTP 202 Accepted even for a dropped event. Its response header identifies rejection by bot filtering:

x-plausible-dropped: 1

A diagnostic request can include this header:

X-Debug-Request: true

The diagnostic response returns HTTP 200 with the IP address Plausible uses for visitor counting, allowing verification of the address forwarded by the proxy.

Related terms

• HTTP Referer header
• Referrer-Policy
• UTM parameters
• Where does Plausible show AI assistant traffic?

FAQ

Can I send a referrer with a custom event?

Yes. The Events API records pageviews and custom events, with referrer available as an optional body parameter. You use your custom event's name in name.

Should I put campaign parameters in the referrer field?

You send the event page's URL in url, including its campaign parameters. The same API documentation specifies that UTM parameters are extracted from that field.

Does an accepted response prove my event appears in reports?

You also need to inspect the response headers. The same API documentation states that a dropped event can return 202 Accepted with x-plausible-dropped: 1.

Sources

1. Plausible, "Plausible Events API reference", 21 September 2026
2. Plausible, "Plausible: GDPR, CCPA and cookie law compliant web analytics", September 2026
3. Plausible, "Traffic sources, referrers and UTM campaigns", 15 October 2026

---

Check how a page reads to answer engines. Open the GEO score analyzer