# 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.

Section: CLI, MCP and API  
Canonical page: https://statsy.co/docs/developers/api-visitors  
Last updated: 2026-09-15

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.

```bash
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.

```bash
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](https://statsy.co/docs/account/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.

Previous: [Realtime API](https://statsy.co/docs/developers/api-realtime)  
Next: [Goals and funnels API](https://statsy.co/docs/developers/api-goals-and-funnels)