Skip to main content

​
GET /api/referrers

Returns the top 10 referrers ranked by distinct visitor count for the given domain and optional date range. Only $pageview events with a non-empty referrer field are included.
Results are hard-limited to 10 entries. Direct traffic (empty referrer) is excluded.

​
Query parameters

​
domain
string
required
The domain to query (e.g. example.com). Must match the d field sent in event payloads exactly.
​
from
string
Start of the date range, inclusive. ISO 8601 date string (YYYY-MM-DD). If omitted, results cover all time up to to.
​
to
string
End of the date range, inclusive. ISO 8601 date string (YYYY-MM-DD). If omitted, results cover all time from from.

​
Response

Returns a JSON array of referrer stat objects, ordered by visitors descending.
​
referrer
string
The full referrer URL as recorded in the event payload (the value of document.referrer in the visitor’s browser).
​
visitors
number
Count of distinct visitor_id values for $pageview events that arrived from this referrer.
Response shape
[
  { "referrer": "https://google.com",         "visitors": 1820 },
  { "referrer": "https://twitter.com",        "visitors": 430  },
  { "referrer": "https://news.ycombinator.com", "visitors": 210 }
]
StatusMeaning
200 OKQuery succeeded (empty array if no referral traffic)
400 Bad Requestdomain query parameter is missing
500 Internal Server ErrorDatabase query failed

​
Examples

curl "https://your-iris-host/api/referrers?domain=example.com&from=2025-01-01&to=2025-01-31"

Build docs developers (and LLMs) love

Get started for freeTalk to us