Source: https://datafa.st/docs/api/website/visitors/list
Markdown source: https://datafa.st/docs/api/website/visitors/list.md
Description: Search visitors by behavior, traffic source, device, location, campaign, customer status, or completed goal.

# 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 | 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. |

### 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.

## 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
  }
}
```