Retrieve visitor data

api-referenceGET

GEThttps://analytics.flowsery.com/analytics/api/v1/visitors/{visitorId}

Fetch identity, activity, revenue, and profile data for a specific visitor using the internal visitorId returned by Flowsery.

Bearer Token (workspace token or website API key)

Workspace tokens need a website selector

Workspace API tokens can access every website in the workspace. Pass either <code>websiteId</code> or <code>domain</code> so Flowsery knows which website to query or mutate. Website API keys are already scoped to one website, so the selector can be omitted.

Website selector

Parameter	Type	Description
`websiteId`	`string`	Website ID to use with a workspace API token. Omit when authenticating with a website API key.
`domain`	`string`	Website domain to use with a workspace API token when websiteId is not provided. Omit when authenticating with a website API key.

Visitor identification

Use the internal visitorId from Flowsery records or API responses. Do not pass the browser _fs_vid cookie directly as the route parameter.

Response fields

Parameter	Type	Description
`identity`	`object`	Geographic location, device type, browser, OS, and viewport dimensions from the most recent pageview
`source`	`string \| null`	Original traffic source that brought this visitor (referrer domain or UTM source)
`sourceIconUrl`	`string \| null`	Favicon URL for the traffic source
`activity`	`object`	Visit and pageview counts, timing info, last URL, completed goals, and visited pages list
`revenue`	`object`	Revenue summary: totalRevenue, isCustomer flag, timeToFirstConversion (seconds, or null)
`profile`	`object \| null`	Identified user data (userId, name, email) if identify was called. Null for anonymous visitors
`activityTimeline`	`array`	Merged chronological list of all pageviews, goal completions, and payments for this visitor

Example request (curl)

curl --request GET \
  --url https://analytics.flowsery.com/analytics/api/v1/visitors/{visitorId} \
  --header 'Authorization: Bearer <api-key>'

200

{
  "status": "success",
  "data": {
    "visitorId": "a3ab2331-989f-4cfa-91c6-2461c9e3c6bd",
    "identity": {
      "country": "South Korea",
      "countryCode": "KR",
      "region": "KR-44",
      "city": "Seosan City",
      "browser": { "name": "Chrome", "version": "133.0.0.0" },
      "os": { "name": "Mac OS", "version": "10.15.7" },
      "device": { "type": "Desktop" },
      "viewport": { "width": 1728, "height": 998 }
    },
    "source": "youtube.com",
    "sourceIconUrl": "https://icons.duckduckgo.com/ip3/youtube.com.ico",
    "activity": {
      "visitCount": 3,
      "pageViewCount": 8,
      "firstVisitAt": "2025-04-11T03:38:49.154Z",
      "lastVisitAt": "2025-04-11T03:38:49.154Z",
      "currentUrl": "example.com/",
      "visitedPages": [
        { "url": "example.com/", "timestamp": "2025-04-11T03:38:49.154Z" }
      ],
      "completedCustomGoals": [
        { "name": "newsletter_signup", "timestamp": "2025-04-11T03:38:54.253Z" }
      ]
    },
    "revenue": {
      "totalRevenue": 29.99,
      "isCustomer": true,
      "timeToFirstConversion": 3600
    },
    "profile": {
      "userId": "usr_123",
      "name": "John Doe",
      "email": "john@example.com"
    },
    "activityTimeline": [
      {
        "type": "payment",
        "timestamp": "2025-04-11T04:38:49.154Z",
        "url": null,
        "eventName": null,
        "amount": 29.99
      },
      {
        "type": "goal",
        "timestamp": "2025-04-11T03:38:54.253Z",
        "url": null,
        "eventName": "newsletter_signup",
        "amount": null
      },
      {
        "type": "pageview",
        "timestamp": "2025-04-11T03:38:49.154Z",
        "url": "example.com/",
        "eventName": null,
        "amount": null
      }
    ]
  }
}