People

Identified visitors on one of the current team's sites — a "site user" is created the moment your app calls identify() for a visitor (see Tracking & events). A site is addressed by {siteKey} (UUID or domain). All endpoints require Authorization: Bearer {token}.

These endpoints return real visitor data — identifier, name, avatar, and behavioral history — for the authenticated team's own visitors only. A site user always belongs to exactly one site; a foreign site user id returns 404, never another team's data.

Both endpoints accept the shared date range and filter query parameters. The date range scopes differently on each: on the list it selects who to return (people last seen in the window); on the profile it scopes the range-bound metrics and timeline, not which person is returned.

List site users

GET /api/sites/{siteKey}/stats/users

Paginated, identified site users last seen inside the resolved date range, ordered by last_seen_at descending. This is a paginated endpoint — it returns the standard data / meta / links envelope (see Conventions).

Query parameters

Plus the shared filter keys, which narrow the behavioral metrics (pageviews, sessions, revenue, etc.) computed for each returned person.

Response — each item in data:

Status: 200 OK.

curl "https://clickbase.so/api/sites/example.com/stats/users?range=last_30_days&per_page=50" \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"

const params = new URLSearchParams({ range: 'last_30_days', per_page: '50' });
await fetch(`https://clickbase.so/api/sites/example.com/stats/users?${params}`, {
  headers: { Authorization: `Bearer ${token}`, Accept: 'application/json' },
});

import requests

requests.get(
    'https://clickbase.so/api/sites/example.com/stats/users',
    params={'range': 'last_30_days', 'per_page': 50},
    headers={'Authorization': f'Bearer {token}', 'Accept': 'application/json'},
)

{
    "data": [
        {
            "id": "1f0a...",
            "identifier": "user_42",
            "name": "Jane Doe",
            "display_name": "Jane Doe",
            "avatar": null,
            "avatar_url": "https://clickbase.so/avatars/....svg",
            "first_seen_at": "2026-06-01T09:12:00.000000Z",
            "last_seen_at": "2026-07-15T14:03:00.000000Z",
            "country": "US",
            "device": "desktop",
            "os": "macOS",
            "browser": "Chrome",
            "source": "Google",
            "referrer_domain": "google.com",
            "pageviews": 42,
            "sessions": 6,
            "spent": 4900,
            "revenue": 4900,
            "recurring_revenue": 4900,
            "activity_days": [false, true, false, false, true, false, false],
            "tracked": true
        }
    ],
    "links": { "first": "...", "last": "...", "prev": null, "next": null },
    "meta": { "current_page": 1, "per_page": 50, "total": 1, "last_page": 1 }
}

Get a site user's profile

GET /api/sites/{siteKey}/stats/users/{siteUser}

A single visitor's profile: identity, range-scoped metrics, up to 8 device/browser session summaries, a ~26-week activity heatmap, and a 100-event timeline (newest first). Scoped to the team's own site — a {siteUser} id belonging to another site (or another team) returns 404.

Path parameters

Query parameters

Plus the shared filter keys.

Response

Status: 200 OK. 404 Not Found when siteUser does not belong to siteKey's site.

curl "https://clickbase.so/api/sites/example.com/stats/users/1f0a1b2c-..." \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"

await fetch('https://clickbase.so/api/sites/example.com/stats/users/1f0a1b2c-...', {
  headers: { Authorization: `Bearer ${token}`, Accept: 'application/json' },
});

import requests

requests.get(
    'https://clickbase.so/api/sites/example.com/stats/users/1f0a1b2c-...',
    headers={'Authorization': f'Bearer {token}', 'Accept': 'application/json'},
)