Skip to main content
Get detailed visitor data including sessions, page views, and behavior.

Endpoint

GET /api/v1/visitor

Authentication

Requires API key authentication.

Parameters

ParameterTypeRequiredDescription
visitorIdstringYesThe visitor ID to retrieve data for

Request example

curl -X GET "https://your-domain.com/api/v1/visitor?visitorId=visitor_123" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

Success response (200)

{
  "status": "success",
  "data": {
    "visitorId": "visitor_123",
    "sessionCount": 5,
    "pageViewCount": 42,
    "firstVisit": "2024-01-15T10:30:00Z",
    "lastVisit": "2024-01-20T14:22:00Z",
    "sessions": [
      {
        "sessionId": "session_456",
        "firstVisitAt": "2024-01-15T10:30:00Z",
        "lastSeenAt": "2024-01-15T10:45:00Z",
        "pageViews": 8,
        "duration": 900,
        "device": "desktop",
        "browser": "chrome",
        "os": "windows",
        "country": "US"
      }
    ],
    "pageViews": [
      {
        "path": "/",
        "title": "Homepage",
        "timestamp": "2024-01-15T10:30:00Z",
        "referrer": "https://google.com"
      }
    ]
  }
}

Error responses

Missing visitorId (400)

{
  "status": "error",
  "error": {
    "code": 400,
    "message": "visitorId parameter is required"
  }
}

Unauthorized (401)

{
  "status": "error",
  "error": {
    "code": 401,
    "message": "Unauthorized. Invalid or missing API key."
  }
}

Response fields

FieldTypeDescription
visitorIdstringThe visitor ID
sessionCountnumberTotal number of sessions
pageViewCountnumberTotal number of page views
firstVisitstringISO 8601 timestamp of first visit
lastVisitstringISO 8601 timestamp of last visit
sessionsarrayArray of session objects
pageViewsarrayArray of page view objects

Session object

FieldTypeDescription
sessionIdstringThe session ID
firstVisitAtstringISO 8601 timestamp
lastSeenAtstringISO 8601 timestamp
pageViewsnumberNumber of page views in session
durationnumberSession duration in seconds
devicestringDevice type (desktop, mobile, tablet)
browserstringBrowser name
osstringOperating system
countrystringCountry code

Page view object

FieldTypeDescription
pathstringPage path
titlestringPage title
timestampstringISO 8601 timestamp
referrerstringReferrer URL

Use cases

  • User journey analysis - See complete visitor journey
  • Support tickets - Get visitor context for support
  • Personalization - Use visitor data for personalization
  • Debugging - Debug tracking issues

Next steps

POST Goal

Learn how to track goal events via API