5 min de lecture

GET /analytics/:websiteId/visitors

Retrieve individual visitor records with geolocation, device information, referrer data, and engagement metrics. Supports pagination for large datasets.

GET/api/external/v1/analytics/:websiteId/visitors

Get visitor data with pagination

Authentication

AuthenticationBash

curl -X GET 'https://api.zenovay.com/api/external/v1/analytics/a1b2c3d4-e5f6-7890-abcd-ef1234567890/visitors?range=7d&limit=50' \
-H 'X-API-Key: YOUR_API_KEY'

Parameters

Name	Type	Required	Default	Description
`websiteId`	string (path)	Yes	-	The UUID of the website
`range`	string (query)	No	`7d`	Time range: `24h`, `7d`, `30d`, `90d`, `1y`
`limit`	integer (query)	No	`100`	Number of records to return (max: 1000)
`offset`	integer (query)	No	`0`	Number of records to skip for pagination

Response

Response (200 OK)JSON

{
"success": true,
"data": {
  "visitors": [
    {
      "id": "v1a2b3c4-d5e6-7890-abcd-ef1234567890",
      "country_code": "US",
      "country_name": "United States",
      "city": "San Francisco",
      "device_type": "desktop",
      "browser": "Chrome",
      "os": "macOS",
      "value_score": 85,
      "visited_at": "2026-02-07T10:30:00.000Z",
      "landing_page": "/pricing",
      "referrer": "https://google.com",
      "had_interaction": true
    },
    {
      "id": "v2b3c4d5-e6f7-8901-bcde-f12345678901",
      "country_code": "GB",
      "country_name": "United Kingdom",
      "city": "London",
      "device_type": "mobile",
      "browser": "Safari",
      "os": "iOS",
      "value_score": 42,
      "visited_at": "2026-02-07T09:15:00.000Z",
      "landing_page": "/",
      "referrer": null,
      "had_interaction": false
    }
  ],
  "pagination": {
    "limit": 100,
    "offset": 0,
    "has_more": true
  }
},
"timestamp": "2026-02-07T12:00:00.000Z"
}

Response Fields

Field	Type	Description
`visitors`	array	List of visitor records
`visitors[].id`	string	Unique visitor identifier
`visitors[].country_code`	string	Two-letter ISO country code
`visitors[].country_name`	string	Full country name
`visitors[].city`	string	City name
`visitors[].device_type`	string	Device type: `desktop`, `mobile`, `tablet`
`visitors[].browser`	string	Browser name
`visitors[].os`	string	Operating system name
`visitors[].value_score`	number	Visitor engagement score (0-100)
`visitors[].visited_at`	string	ISO 8601 visit timestamp
`visitors[].landing_page`	string	URL of the first page visited
`visitors[].referrer`	string\|null	Referring URL, null for direct visits
`visitors[].had_interaction`	boolean	Whether the visitor interacted with the page
`pagination.limit`	number	Records per page
`pagination.offset`	number	Current offset
`pagination.has_more`	boolean	Whether more records are available

TypeScript Interface

VisitorsResponseTypeScript

interface Visitor {
id: string;
country_code: string;
country_name: string;
city: string;
device_type: string;
browser: string;
os: string;
value_score: number;
visited_at: string;
landing_page: string;
referrer: string | null;
had_interaction: boolean;
}

interface VisitorsResponse {
success: true;
data: {
  visitors: Visitor[];
  pagination: {
    limit: number;
    offset: number;
    has_more: boolean;
  };
};
timestamp: string;
}

HTTP Status Codes

Status Code	Description
200	Success
400	Bad Request - Invalid parameters
401	Unauthorized - Invalid or missing API key
403	Forbidden - API key does not have access to this website
404	Not Found - Website not found
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error

Code Examples

cURLBash

curl -X GET 'https://api.zenovay.com/api/external/v1/analytics/a1b2c3d4-e5f6-7890-abcd-ef1234567890/visitors?range=7d&limit=50&offset=0' \
-H 'X-API-Key: YOUR_API_KEY' \
-H 'Content-Type: application/json'

Error Handling

Error Response (500 Internal Server Error)JSON

{
"success": false,
"error": {
  "message": "Failed to fetch visitor data",
  "code": "INTERNAL_ERROR",
  "timestamp": "2026-02-07T12:00:00.000Z"
}
}