List visitors

GET https://datafa.st/api/v1/visitors

Search visitors by behavior, traffic source, device, location, campaign, customer status, or completed goal.

Request

Authentication

df_ website API key for one website.
dft_ account token with analytics:read. Pass websiteId as a query parameter.

Query parameters

Parameter	Type	Required	Description
`startAt`	string	No	Sets the beginning of the reporting window. Use it when you want a specific date range instead of the endpoint default. Must be provided with `endAt`. Example: `startAt=2026-05-01`.
`endAt`	string	No	Sets the end of the reporting window. Must be provided with `startAt`. Example: `endAt=2026-05-21`.
`timezone`	string	No	Controls how dates are interpreted and how time buckets are grouped. Defaults to the website timezone. Example: `timezone=America/New_York`.
`limit`	number	No	Maximum number of rows returned in one response. Use with `offset` to paginate through long result sets. Number of visitors to return. Defaults to 100, max 250.
`offset`	number	No	Number of rows to skip before returning results. Use it with `limit` for pagination.
`visitedPage / page`	string	No	Exact page path. Comma-separated values supported, max 50 values.
`visitedPageContains / pageContains`	string	No	Partial page match.
`completedGoal / goal`	string	No	Return visitors who completed this goal.
`country, region, city`	string	No	Location filters.
`browser, os, device`	string	No	Browser, OS, and device filters.
`referrer, hostname`	string	No	Traffic source and hostname filters.
`utm_source, utm_medium, utm_campaign, utm_term, utm_content`	string	No	UTM filters.
`ref, source, via`	string	No	URL parameter filters.
`isCustomer / hasRevenue`	`true` or `false`	No	Filter visitors with or without payment events. Cannot be combined with `completedGoal`.

Response

Returns a JSON object with status and endpoint-specific fields.

Response fields

Field	Type	Description
`data[].visitorId`	string	Alias for `datafast_visitor_id` on endpoints that accept both names.
`data[].lastSeenAt`	string	null
`data[].currentUrl`	string	null
`data[].identity.country`	string	null
`data[].identity.region`	string	null
`data[].identity.city`	string	null
`data[].identity.browser`	string	null
`data[].identity.os`	string	null
`data[].identity.device`	string	null
`data[].acquisition.*`	string	null
`pagination.limit`	number	Maximum number of rows returned in one response. Use with `offset` to paginate through long result sets.
`pagination.offset`	number	Number of rows to skip before returning results. Use it with `limit` for pagination.
`pagination.total`	number	Total matching visitors.
`pagination.hasMore`	boolean	Whether more results are available.

Errors

Common errors include 400 for invalid input, 401 for missing or invalid tokens, 403 for missing permission or suspended tracking, 404 for missing resources, and 500 for server errors.

✍️ Something missing? Suggest features.

🤖 AI agent or LLM? Read this page as markdown

{ "status": "success", "data": [{ "visitorId": "a3ab2331-989f-4cfa-91c6-2461c9e3c6bd", "lastSeenAt": "2026-05-05T12:00:00Z", "currentUrl": "example.com/pricing", "identity": { "country": "US", "region": "CA", "city": "San Francisco", "browser": "Chrome", "os": "Mac OS", "device": "desktop" }, "acquisition": { "referrer": "Google", "utm_source": "google", "utm_campaign": "launch" } }], "pagination": { "limit": 100, "offset": 0, "total": 1234, "hasMore": true } }