# Query Visitors

> Find visitors with matching events and search current profiles through the Ours Privacy Platform API.

Source: https://docs.oursprivacy.com/docs/platform-api/query-visitors

Use Query Visitors to find visitor IDs with matching events in an inclusive date range. Add event filters, first- or last-touch UTM filters, and profile search results to narrow the list. JSON-encode the `input` object in the query string, then continue with `pagination.nextCursor` while `hasMore` is true.

The list includes matching-event counts and current profile fields the caller may view. Profile search returns visitor IDs to pass into the list input and requires visitor-profile access.

## GET /rest/v1/query-visitors

List visitors with matching events and their permitted current-profile fields. JSON-encode input in the query string; cursors stay bound to the account and filters, while page size may change. Requires API-key scope or current OAuth user permission: web-analytics:view, report:list-events

Request URL: `GET https://app.oursprivacy.com/rest/v1/query-visitors`

Authentication: apiKey or oauth2.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `input` | query | string | Yes | Query Visitors filters and page. JSON-encode input in the REST query string. Query Visitors filters and page. JSON-encode input in the REST query string. |

### Responses

- `200`: Query Visitors page
- `400`: Invalid visitor filters, date range, or cursor.
- `401`: Unauthorized — missing, invalid, or expired API key or OAuth access token
- `403`: Analytics viewing and event-listing permissions are required.
- `404`: Not Found
- `500`: Internal Server Error

#### `200` response body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `rows` | object[] | Yes |  |
| `rows[].visitorId` | string | Yes |  |
| `rows[].match` | object | Yes |  |
| `rows[].match.eventCount` | number | Yes |  |
| `rows[].match.firstEventAt` | string (date-time) | Yes |  |
| `rows[].match.lastEventAt` | string (date-time) | Yes |  |
| `rows[].profile` | object | Yes |  |
| `rows[].profile.status` | string | Yes | Current profile lookup status. One of: `"FOUND"`, `"NOT_FOUND"`, `"UNAVAILABLE"`. |
| `rows[].profile.email` | string \| null | Yes | Current profile email, when available. |
| `rows[].profile.firstName` | string \| null | Yes | Current first name, when permitted and available. |
| `rows[].profile.lastName` | string \| null | Yes | Current last name, when permitted and available. |
| `rows[].profile.externalId` | string \| null | Yes | Current external ID, when available. |
| `rows[].profile.firstSeenAt` | string \| null (date-time) | Yes | First activity recorded on the current profile. |
| `rows[].profile.lastSeenAt` | string \| null (date-time) | Yes | Most recent activity recorded on the current profile. |
| `matchedCount` | number \| null | Yes |  |
| `pagination` | object | Yes |  |
| `pagination.hasMore` | boolean | Yes |  |
| `pagination.nextCursor` | string \| null | Yes |  |
| `freshness` | object | Yes |  |
| `freshness.coverageWatermark` | string \| null (date-time) | Yes |  |
| `freshness.coverageStatus` | string | Yes | One of: `"UNKNOWN"`. |
| `freshness.syncCursor` | string \| null (date-time) | No |  |
| `freshness.syncCompletedAt` | string \| null (date-time) | No |  |

Full schema: [OpenAPI specification](https://docs.oursprivacy.com/openapi-platform.json).

## GET /rest/v1/query-visitors/capabilities

Return Query Visitors date, page, selection, and touch-filter capabilities. Requires API-key scope or current OAuth user permission: web-analytics:view, report:list-events

Request URL: `GET https://app.oursprivacy.com/rest/v1/query-visitors/capabilities`

Authentication: apiKey or oauth2.

### Responses

- `200`: Query Visitors capabilities
- `400`: Bad Request
- `401`: Unauthorized — missing, invalid, or expired API key or OAuth access token
- `403`: Forbidden — credential does not have the required current Ours permission
- `404`: Not Found
- `500`: Internal Server Error

#### `200` response body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `version` | number | Yes | One of: `1`. |
| `defaultPageSize` | number | Yes | One of: `25`. |
| `maxPageSize` | number | Yes | One of: `100`. |
| `maxDateRangeDays` | number | Yes | One of: `31`. |
| `maxSelections` | number | Yes | One of: `10`. |
| `touchEnabled` | boolean | Yes |  |
| `touchLookbackDays` | integer[] | Yes |  |
| `defaultTouchLookbackDays` | integer | Yes |  |
| `supportsVerifiedCoverageWatermark` | boolean | Yes |  |

Full schema: [OpenAPI specification](https://docs.oursprivacy.com/openapi-platform.json).

## GET /rest/v1/query-visitors/profile-search

Search current visitor profiles for the Query Visitors typeahead. Pass returned visitorIds to the list input to filter the result. Requires API-key scope or current OAuth user permission: web-analytics:view, report:list-events, report:view-visitor

Request URL: `GET https://app.oursprivacy.com/rest/v1/query-visitors/profile-search`

Authentication: apiKey or oauth2.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `input` | query | string | Yes | Current profile search filters. JSON-encode input in the REST query string. Current profile search filters. JSON-encode input in the REST query string. |

### Responses

- `200`: Current visitor profiles
- `400`: Bad Request
- `401`: Unauthorized — missing, invalid, or expired API key or OAuth access token
- `403`: Analytics viewing, event listing, and visitor-view permissions are required.
- `404`: Not Found
- `500`: Internal Server Error

#### `200` response body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `matches` | object[] | Yes |  |
| `matches[].visitorId` | string | Yes |  |
| `matches[].email` | string \| null | Yes |  |
| `matches[].firstName` | string \| null | Yes |  |
| `matches[].lastName` | string \| null | Yes |  |
| `matches[].externalId` | string \| null | Yes |  |
| `matches[].lastSeenAt` | string \| null (date-time) | Yes |  |
| `visitorIds` | string[] | Yes |  |
| `truncated` | boolean | Yes |  |

Full schema: [OpenAPI specification](https://docs.oursprivacy.com/openapi-platform.json).

## Next Steps

* [Query Events API](https://docs.oursprivacy.com/docs/platform-api/query-events)
* [Insights API](https://docs.oursprivacy.com/docs/platform-api/insights)
* [MCP server](https://docs.oursprivacy.com/docs/platform-mcp)
