Source: https://datafa.st/docs/api/website/visitors/retrieve
Markdown source: https://datafa.st/docs/api/website/visitors/retrieve.md
Description: Retrieve the full profile for one visitor: identity, session activity, completed goals, payment events, Identify profile, and conversion prediction. Use the `visitorId` returned by [List visitors](/docs/api-list-visitors) or stored in the `datafast_visitor_id` cookie.

# Get visitor

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

Retrieve the full profile for one visitor: identity, session activity, completed goals, payment events, Identify profile, and conversion prediction. Use the `visitorId` returned by [List visitors](/docs/api/website/visitors/list) or stored in the `datafast_visitor_id` cookie.

This is the endpoint to call when you need journey context for support, sales, or enrichment — not for bulk exports.

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

## Request

#### Path parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `visitorId` | string | — | Alias for `datafast_visitor_id` on endpoints that accept both names. Visitor UUID from [List visitors](/docs/api/website/visitors/list) or the browser cookie. |

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

#### Example request

```http
GET /api/v1/visitors/a3ab2331-989f-4cfa-91c6-2461c9e3c6bd
```

Use the UUID from [List visitors](/docs/api/website/visitors/list) or the `datafast_visitor_id` cookie.

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

## 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** — Missing or invalid `visitorId` (must be a UUID v4), or visitor flagged as a bot.

**404** — No pageviews found for this visitor on the authenticated website.

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/{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
    }
  }
}
```