Visitors and journeys API
Search visitors by id, email, name, country, city or path, and read one visitor’s full timeline of pages, goals and payments.
Two endpoints cover individual people: a search that lists visitors, and a journey that shows everything one of them did.
Search visitors
GET /sites/:site/visitors lists visitors in a range, newest activity first, with their identity if the site called statsy.identify() and their lifetime value if they paid.
curl -G -H "Authorization: Bearer sta_your_token" \
--data-urlencode "query=acme.com" \
"https://statsy.co/api/v1/sites/ws_yoursitekey/visitors?from=30d&limit=50"| Parameter | Notes |
|---|---|
query | Free text. Matches visitor id, email, name, user id, country, city and path. |
limit | Defaults to 50, maximum 200. |
cursor | From the previous response’s cursor. null means the last page. |
filters | The standard filter array, plus the usual range parameters. |
One visitor’s journey
GET /sites/:site/visitors/:id/journey merges pageviews, goals, marketing touches and payments into one time-ordered list, so you can read a purchase backwards from the sale to the post that started it.
curl -H "Authorization: Bearer sta_your_token" \
"https://statsy.co/api/v1/sites/ws_yoursitekey/visitors/VISITOR_ID/journey?from=90d"limit defaults to 500 and tops out at 2,000. There is no cursor: raise the limit or narrow the range instead. If you omit the range, the journey covers the last 90 days.
Visitor identifiers
In Full mode the visitor id is the value of the first-party statsy_vid cookie, which is also what statsy.visitorId() returns in the browser. That is the id to pass through checkout so a payment can be credited to the visit that led to it.
In cookieless mode there is no stored identifier, and ids look like anon_<hash>. They are derived from a secret that changes every day and is deleted afterwards, so they never link across days and cannot be traced back to an IP address.
How far back this goes
Both endpoints read raw events and sessions, which are kept for 90 days. Ask for more and the range is clamped, with clamped: true in the response. Aggregate reports are not affected. See Data retention.
Note. Visitor-level data is never exposed through share links, no matter how a dashboard is shared. It is only available to signed-in people and to tokens.
Last updated · Markdown version