Source: https://datafa.st/docs/api/website/visitors/retrieve
Markdown source: https://datafa.st/docs/api/website/visitors/retrieve.md
Description: Retrieve identity, activity, profile, completed goals, payment, and prediction data for one visitor.

# Get visitor

`GET https://datafa.st/api/v1/visitors/{visitorId}`

Retrieve identity, activity, profile, completed goals, payment, and prediction data for one visitor.

## Request

### Authentication

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


### Path parameters

| Parameter | Type | Description |
| --- | --- | --- |
| `visitorId` | string | Alias for `datafast_visitor_id` on endpoints that accept both names. Visitor UUID returned by list visitors or stored in the visitor cookie. |

## 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.identity` | object | Location, browser, operating system, device, viewport, and first-session parameters known for the visitor. Location, browser, OS, device, viewport, params, and ad click IDs. |
| `data.identity.country` | string|null | Country name inferred from the visitor's latest pageview. |
| `data.identity.countryCode` | string|null | Two-letter country code when available. |
| `data.identity.region` | string|null | Region or state when available. |
| `data.identity.city` | string|null | City when available. |
| `data.identity.params` | object | URL parameters captured on the first session, such as `ref`, `source`, `via`, and UTM fields. |
| `data.identity.adClickIds` | object | Captured ad click IDs such as Google or Meta click identifiers. |
| `data.identity.browser` | object | Browser details. |
| `data.identity.browser.name` | string|null | Human-readable name for the resource or event. The exact meaning depends on the endpoint. |
| `data.identity.browser.version` | string|null | Browser version when available. |
| `data.identity.os` | object | Operating system details. |
| `data.identity.os.name` | string|null | Human-readable name for the resource or event. The exact meaning depends on the endpoint. Operating system name, such as `Mac OS`, `Windows`, `iOS`, or `Android`. |
| `data.identity.os.version` | string|null | Operating system version when available. |
| `data.identity.device` | object | Device details. |
| `data.identity.device.type` | string|null | Device type such as `desktop`, `mobile`, or `tablet`. |
| `data.identity.device.vendor` | string|null | Device vendor when available. |
| `data.identity.device.model` | string|null | Device model when available. |
| `data.identity.viewport` | object | Viewport dimensions captured from the pageview. |
| `data.identity.viewport.width` | number|null | Viewport width in pixels. |
| `data.identity.viewport.height` | number|null | Viewport height in pixels. |
| `data.activity.visitCount` | number | Number of visits. |
| `data.activity.pageViewCount` | number | Number of pageviews. |
| `data.activity.timeSinceFirstVisit` | number | Milliseconds since this visitor's first known visit. |
| `data.activity.timeSinceCurrentVisit` | number | Milliseconds since this visitor's current/latest visit started. |
| `data.activity.firstVisitAt` | string|null | Timestamp of the first known visit. |
| `data.activity.lastVisitAt` | string|null | Timestamp of the latest known visit. |
| `data.activity.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.activity.completedGoals` | object[] | Custom, payment, free trial, and subscription lifecycle goals. |
| `data.activity.completedGoals.name` | string | Human-readable name for the resource or event. The exact meaning depends on the endpoint. |
| `data.activity.completedGoals.origin` | string | `manual` for custom goals or `payment_provider` for provider events. |
| `data.activity.completedGoals.type` | string | Goal type such as `custom`, `payment`, or `subscription_lifecycle`. |
| `data.activity.completedGoals.timestamp` | string | Event timestamp. Use it when recording historical events; defaults to the request time. |
| `data.activity.visitedPages` | object[] | Visited page timeline. |
| `data.activity.visitedPages.url` | string | Visited page URL or path. |
| `data.activity.visitedPages.timestamp` | string | Event timestamp. Use it when recording historical events; defaults to the request time. |
| `data.profile` | object|null | User profile created by Identify. Present only after the visitor has been linked to your user ID. Identify profile with `userId`, `metadata`, and `identifiedAt`. |
| `data.profile.userId` | string | Your user ID passed to Identify. |
| `data.profile.metadata` | object | Custom metadata stored with the event or profile. Use this to enrich reporting and visitor profiles. |
| `data.profile.identifiedAt` | string | Timestamp when this profile was created or updated. |
| `data.prediction` | object|null | Conversion prediction for the visitor when enough revenue attribution data exists. Conversion prediction. Null for customers or when predictions are unavailable. |
| `data.prediction.score` | number | 0-100 lead score. Higher means the visitor is more likely to convert. |
| `data.prediction.conversionRate` | number | Predicted conversion rate for this visitor. |
| `data.prediction.expectedValue` | number | Predicted revenue value in USD. |
| `data.prediction.confidence` | number | 0-1 confidence score for the prediction. |

### 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/{visitorId}" \
  -H "Authorization: Bearer df_xxx"
```

### Success response

```json
{
  "status": "success",
  "data": {
    "visitorId": "a3ab2331-989f-4cfa-91c6-2461c9e3c6bd",
    "identity": {
      "country": "US",
      "browser": { "name": "Chrome" },
      "device": { "type": "desktop" }
    },
    "activity": {
      "visitCount": 3,
      "pageViewCount": 8,
      "completedGoals": [],
      "visitedPages": []
    },
    "profile": {
      "userId": "user_123",
      "metadata": { "plan": "pro" },
      "identifiedAt": "2026-05-21T00:00:00.000Z"
    },
    "prediction": {
      "score": 72,
      "conversionRate": 0.0138,
      "expectedValue": 3.09,
      "confidence": 0.831
    }
  }
}
```