Source: https://datafa.st/docs/api-list-visitors
Markdown source: https://datafa.st/docs/api-list-visitors.md
Description: Search visitors by page, goal, source, device, location, or campaign.

# List visitors

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

Search visitor IDs by behavior and filters, then use [Get visitor data](/docs/api-get-visitor) to drill into a single visitor. Requires [Bearer Token](/docs/api-introduction) authentication.

## Common use cases

- Find visitors who visited a specific page
- Find visitors who completed a goal
- Find mobile visitors from Google in a specific country
- Find visitors from a UTM campaign

## Query parameters

| Parameter | Description |
|---|---|
| `startAt` / `endAt` | Optional date range. Use `YYYY-MM-DD` for calendar days or ISO timestamps with `Z`/offset for exact instants. Both must be provided together. |
| `limit` | Number of visitors to return. Default `100`, max `250`. |
| `offset` | Number of visitors to skip. Default `0`. |
| `visitedPage` | Exact page path, e.g. `/pricing`. |
| `visitedPageContains` | Partial page match, e.g. `/docs`. |
| `completedGoal` | Visitors who completed a goal or event, e.g. `signup`. |
| `country`, `region`, `city` | Location filters. Country names and country codes are supported. |
| `device`, `browser`, `os` | Device and browser filters. |
| `referrer`, `hostname` | Traffic source and hostname filters. |
| `utm_source`, `utm_medium`, `utm_campaign`, `utm_term`, `utm_content` | UTM filters. |
| `ref`, `source`, `via` | URL parameter filters. |
| `isCustomer=true` | Visitors with a payment event. |

## Examples

```http
GET /api/v1/visitors?visitedPage=/pricing&startAt=2026-04-01&endAt=2026-05-01
GET /api/v1/visitors?visitedPageContains=/docs&completedGoal=signup&limit=100
GET /api/v1/visitors?referrer=Google&country=France&device=mobile
GET /api/v1/visitors?utm_campaign=launch&isCustomer=true
```

## Response

The `data` array contains up to `limit` matching visitors. Use `pagination.offset`, `pagination.limit`, and `pagination.hasMore` to fetch more results.

```json
{
  "status": "success",
  "data": [
    {
      "visitorId": "a3ab2331-989f-4cfa-91c6-2461c9e3c6bd",
      "lastSeenAt": "2026-05-05T12:00:00Z",
      "currentUrl": "datafa.st/pricing",
      "identity": {
        "country": "US",
        "region": "CA",
        "city": "San Francisco",
        "browser": "Chrome",
        "os": "Mac OS",
        "device": "desktop"
      },
      "acquisition": {
        "referrer": "https://google.com",
        "utm_source": "google",
        "utm_campaign": "launch"
      }
    },
    {
      "visitorId": "7c5d3f16-6f9f-4d1b-9d9d-8fb74f6e3b6a",
      "lastSeenAt": "2026-05-04T18:30:00Z",
      "currentUrl": "datafa.st/docs/api-introduction",
      "identity": {
        "country": "FR",
        "region": "IDF",
        "city": "Paris",
        "browser": "Safari",
        "os": "iOS",
        "device": "mobile"
      },
      "acquisition": {
        "referrer": "https://x.com",
        "utm_source": null,
        "utm_campaign": null
      }
    }
    // More matching visitors can be returned here, up to the requested limit.
  ],
  "pagination": {
    "limit": 100,
    "offset": 0,
    "total": 1234,
    "hasMore": true
  }
}
```

> This endpoint is paginated on purpose. Use it to find matching visitor IDs, then call `GET /api/v1/visitors/{datafast_visitor_id}` for full visitor details.

## 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 YOUR_API_KEY"
```

### Success response

```json
{
  "status": "success",
  "data": [
    {
      "visitorId": "a3ab2331-989f-4cfa-91c6-2461c9e3c6bd",
      "lastSeenAt": "2026-05-05T12:00:00Z",
      "currentUrl": "datafa.st/pricing",
      "identity": {
        "country": "US",
        "region": "CA",
        "city": "San Francisco",
        "browser": "Chrome",
        "os": "Mac OS",
        "device": "desktop"
      },
      "acquisition": {
        "referrer": "https://google.com",
        "utm_source": "google",
        "utm_campaign": "launch"
      }
    },
    {
      "visitorId": "7c5d3f16-6f9f-4d1b-9d9d-8fb74f6e3b6a",
      "lastSeenAt": "2026-05-04T18:30:00Z",
      "currentUrl": "datafa.st/docs/api-introduction",
      "identity": {
        "country": "FR",
        "region": "IDF",
        "city": "Paris",
        "browser": "Safari",
        "os": "iOS",
        "device": "mobile"
      },
      "acquisition": {
        "referrer": "https://x.com",
        "utm_source": null,
        "utm_campaign": null
      }
    }
    // More matching visitors can be returned here, up to the requested limit.
  ],
  "pagination": {
    "limit": 100,
    "offset": 0,
    "total": 1234,
    "hasMore": true
  }
}
```