List visitors

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

Search for visitor IDs by page views, goals, traffic source, device, location, or campaign parameters. Use this endpoint to find matching visitors, then call Get visitor for the full profile, activity timeline, and prediction data.

This endpoint is paginated on purpose — it returns lightweight rows suitable for search and CRM enrichment workflows.

When searching by completedGoal, results come from journey analytics and lastSeenAt reflects goal completion time rather than the latest pageview. Visitor session metadata is available for normal tracker events collected after the session-count rollout; old or cookieless events may return null.

Related: User identification · Revenue prediction

Try on Playground

Request

Query parameters

websiteId

string

Required with a dft_ account token on Website API routes. Omit with a df_ website key. Example: ?websiteId=665f0b3c4d2e1a0012345678.

startAt

string

Start of the reporting window. Use YYYY-MM-DD for calendar days or an ISO timestamp. Must be provided together with endAt. Example: startAt=2026-05-01.

endAt

string

End of the reporting window. Must be provided together with startAt. Example: endAt=2026-05-21.

timezone

string

Timezone used to interpret dates and group analytics buckets. Defaults to the website timezone. IANA timezone for dashboard periods and API date grouping. Examples: "America/New_York", "Europe/Paris", "UTC". Defaults to the website timezone when omitted.

limit

number

Visitors to return. Default 100, maximum 250. Example: limit=50.

offset

number

Visitors to skip. Default 0. Example: offset=100.

visitedPage / page

string

Exact page path match. Comma-separated, max 50 values. Example: visitedPage=/pricing or page=/docs/getting-started.

visitedPageContains / pageContains

string

Partial page path match. Example: visitedPageContains=/docs.

completedGoal / goal

string

Visitors who completed this custom goal. Example: completedGoal=signup. Cannot combine with isCustomer or hasRevenue.

visitCount / visit_count

number

Visitors whose all-time tracked session number matches this value. Example: visitCount=2 for second-session visitors.

country, region, city

string

Location filters. Country names and ISO codes supported. Max 50 comma-separated values. Example: country=US,Canada.

browser, os, device

string

Device filters. Example: device=mobile&browser=Chrome.

referrer, hostname

string

Traffic source and hostname. Example: referrer=Google.

utm_source, utm_medium, utm_campaign, utm_term, utm_content

string

UTM filters. Example: utm_source=google&utm_campaign=launch.

ref, source, via

string

First-session URL params. Example: ref=twitter.

isCustomer / hasRevenue

true or false

Set either parameter to true to return visitors with payment events. false is accepted but currently leaves the visitor list unfiltered; it does not mean non-customers. Cannot combine true with completedGoal.

Example query

GET /api/v1/visitors?visitedPage=/pricing&completedGoal=signup&limit=50&startAt=2026-05-01&endAt=2026-05-21

Returns lightweight rows — call Get visitor for full journey data.

Response

Returns a JSON object with status: "success" and endpoint-specific fields in data (and pagination when the endpoint is paginated).

Response fields

data[].visitorId

string

Alias for datafast_visitor_id on endpoints that accept both names.

data[].lastSeenAt

string|null

Timestamp of the visitor's latest matching activity. Use it to sort or sync recently active visitors. Last seen timestamp or goal completion timestamp when searching by goal.

data[].visitorFirstSeenAt

string|null

First-seen timestamp from the tracker cookie. Null for old or cookieless events.

data[].visitorSessionNumber

number|null

All-time session number from the tracker cookie. 1 is new, 2+ is returning. Null when unavailable.

data[].visitorType

new|returning|null

Derived from visitorSessionNumber. Null when session metadata is unavailable.

data[].currentUrl

string|null

Latest page URL seen for the visitor. Use it to understand where the visitor was last active before you inspect the full visitor profile.

data[].identity.country

string|null

Country.

data[].identity.region

string|null

Region or state.

data[].identity.city

string|null

City.

data[].identity.browser

string|null

Browser name.

data[].identity.os

string|null

Operating system.

data[].identity.device

string|null

Device type.

data[].acquisition.*

string|null

Referrer and campaign parameters.

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.

Authentication

df_ website API key: The website is inferred from the key. You do not need a websiteId query parameter.
dft_ account token: Requires analytics:read permission and ?websiteId= on every request. The token must be allowed to access that website.

Read authentication and scopes for token creation, permission lists, and scoped tokens.

Errors

400 — Unsupported query parameter, limit above 250, invalid isCustomer/hasRevenue value, combining completedGoal with isCustomer/hasRevenue, or using didNotCompleteGoal/goalNot (not supported).

404 — Website not found.

See API errors for the standard error envelope, auth failures, validation errors, permission errors, and rate limits.

✍️ Something missing? Suggest features.

🤖 AI agent or LLM? Read this page as markdown