Source: https://datafa.st/docs/api/website/visitors/list
Markdown source: https://datafa.st/docs/api/website/visitors/list.md
Description: 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](/docs/api-get-visitor) for the full profile, activity timeline, and prediction data.

# 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](/docs/api/website/visitors/retrieve) 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.

> **Related:** [User identification](/docs/user-identification) · [Revenue prediction](/changelog/revenue-prediction)

## Request

#### Query parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `websiteId` | string | Required with dft_ | Required with a `dft_` account token on Website API routes. Omit with a `df_` website key. Example: `?websiteId=665f0b3c4d2e1a0012345678`. |
| `startAt` | string | No* | 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 | No* | End of the reporting window. Must be provided together with `startAt`. Example: `endAt=2026-05-21`. |
| `timezone` | string | No | 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 | No | Visitors to return. Default `100`, maximum `250`. Example: `limit=50`. |
| `offset` | number | No | Visitors to skip. Default `0`. Example: `offset=100`. |
| `visitedPage / page` | string | No | Exact page path match. Comma-separated, max 50 values. Example: `visitedPage=/pricing` or `page=/docs/getting-started`. |
| `visitedPageContains / pageContains` | string | No | Partial page path match. Example: `visitedPageContains=/docs`. |
| `completedGoal / goal` | string | No | Visitors who completed this custom goal. Example: `completedGoal=signup`. Cannot combine with `isCustomer` or `hasRevenue`. |
| `country, region, city` | string | No | Location filters. Country names and ISO codes supported. Max 50 comma-separated values. Example: `country=US,Canada`. |
| `browser, os, device` | string | No | Device filters. Example: `device=mobile&browser=Chrome`. |
| `referrer, hostname` | string | No | Traffic source and hostname. Example: `referrer=Google`. |
| `utm_source, utm_medium, utm_campaign, utm_term, utm_content` | string | No | UTM filters. Example: `utm_source=google&utm_campaign=launch`. |
| `ref, source, via` | string | No | First-session URL params. Example: `ref=twitter`. |
| `isCustomer / hasRevenue` | `true` or `false` | No | Filter visitors with (`true`) or without (`false`) payment events. Cannot combine with `completedGoal`. |

#### Example query

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

Returns lightweight rows — call [Get visitor](/docs/api/website/visitors/retrieve) 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

| Field | Type | Description |
| --- | --- | --- |
| `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[].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](/docs/api/authentication) 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](/docs/api#errors) for the standard error envelope, auth failures, validation errors, permission errors, and rate limits.

## Code examples

### Example request

```bash
curl -X GET "https://datafa.st/api/v1/visitors?visitedPage=/pricing&startAt=2026-04-01&endAt=2026-05-01&limit=100" \
  -H "Authorization: Bearer df_xxx"
```

### Success response

```json
{
  "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
  }
}
```