API

List profiles

GEThttps://api.visitors.now/v1/profiles

Returns a paginated list of visitor profiles for the project.

Request

index.ts
const res = await fetch("https://api.visitors.now/v1/profiles?period=30d&limit=20", {
  headers: { Authorization: `Bearer ${VISITORS_API_KEY}` },
});

const { items, nextCursor } = await res.json();

Query parameters

period

string

Time period. One of today, yesterday, 24h, 7d, 30d, 3m, 6m, 12m, this_week, this_month, this_year, all_time, custom. Default: 30d.

start

string

Custom start date (ISO 8601). Overrides period.

end

string

Custom end date (ISO 8601). Overrides period.

tz

string

Timezone for date calculations. Default: UTC.

sort

string

Sort order. One of recent, oldest, activity, sessions, revenue. Default: recent.

search

string

Search profiles by name or ID.

filters

string

JSON-encoded filter object.

cursor

string

Pagination cursor from a previous response.

limit

number

Number of results per page (1-200). Default: 50.

Response

{
  "items": [
    {
      "id": "v_abc123",
      "project_id": "proj_123",
      "name": "John Doe",
      "avatar": null,
      "anonymous": 0,
      "first_seen_at": "2026-02-01T10:00:00.000Z",
      "last_seen_at": "2026-03-07T12:04:30.000Z",
      "first_seen_on": "/",
      "last_seen_on": "/pricing",
      "sessions": 12,
      "pageviews": 47,
      "events": 5,
      "first_geoname_id": 2643743,
      "first_city": "London",
      "first_region": "England",
      "first_region_code": "ENG",
      "first_country": "United Kingdom",
      "first_country_code": "GB",
      "first_referrer_name": "Google",
      "first_referrer_type": "search",
      "first_referrer_url": "https://google.com",
      "first_utm_source": "google",
      "first_utm_medium": "cpc",
      "first_utm_campaign": "spring",
      "first_utm_content": "",
      "first_utm_term": "",
      "first_browser": "Chrome",
      "first_browser_version": "122.0.0",
      "first_engine": "Blink",
      "first_engine_version": "122.0.0",
      "first_os": "macOS",
      "first_os_version": "14.3.0",
      "first_device": "Desktop",
      "first_device_vendor": "Apple",
      "first_device_model": "",
      "first_cpu_architecture": "arm64",
      "last_geoname_id": 2643743,
      "last_city": "London",
      "last_region": "England",
      "last_region_code": "ENG",
      "last_country": "United Kingdom",
      "last_country_code": "GB",
      "last_referrer_name": "",
      "last_referrer_type": "direct",
      "last_referrer_url": "",
      "last_utm_source": "",
      "last_utm_medium": "",
      "last_utm_campaign": "",
      "last_utm_content": "",
      "last_utm_term": "",
      "last_browser": "Chrome",
      "last_browser_version": "122.0.0",
      "last_engine": "Blink",
      "last_engine_version": "122.0.0",
      "last_os": "macOS",
      "last_os_version": "14.3.0",
      "last_device": "Desktop",
      "last_device_vendor": "Apple",
      "last_device_model": "",
      "last_cpu_architecture": "arm64",
      "revenue": 49.99
    }
  ],
  "nextCursor": "eyJ2IjoxNzA5..."
}