# Web Analytics

> Query privacy-first website traffic metrics, timeseries, and page, source, location, device, and journey breakdowns through the REST API.

Source: https://docs.oursprivacy.com/docs/platform-api/web-analytics

Query privacy-first website traffic reports for an inclusive calendar-day range. Scope results to one web source or aggregate across the account, and use the JSON-encoded `filters` query parameter to narrow reports by supported dimensions.

## GET /rest/v1/web-analytics/overview

Return privacy-first traffic metrics and a timeseries for the requested date range. Filter by source, geography, page, campaign, device, or other supported dimensions with the JSON-encoded `filters` query parameter. Requires API-key scope or current OAuth user permission: web-analytics:view

Request URL: `GET https://app.oursprivacy.com/rest/v1/web-analytics/overview`

Authentication: apiKey or oauth2.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `from` | query | string (date) | Yes | Inclusive lower bound of the analysis window as `YYYY-MM-DD`. |
| `to` | query | string (date) | Yes | Inclusive upper bound of the analysis window as `YYYY-MM-DD`. |
| `webSourceId` | query | string (uuid) | No | Optional web source UUID. Omit to aggregate all web sources in the account. |
| `excludeBots` | query | boolean | No | Exclude detected bot sessions. Defaults to true. |
| `filters` | query | string | No | JSON-encoded query input. Optional JSON-encoded array of up to 20 filters. Dimensions: `page`, `entry_page`, `exit_page`, `source`, `medium`, `campaign`, `content`, `term`, `referrer`, `country`, `region`, `city`, `device`, `browser`, `os`. Each filter has a dimension, optional operator (`IS`, `IS_NOT`, `CONTAINS`, `NOT_CONTAINS`; defaults to `IS`), and one or more values. Example: `[{"dimension":"country","values":["United States"]}]`. |
| `interval` | query | string | Yes | Timeseries bucket interval. Minute queries are capped to the most recent 24 hours. One of: `"minute"`, `"day"`, `"week"`, `"month"`. |
| `metric` | query | string | Yes | One of: `"unique_visitors"`, `"total_visits"`, `"pageviews"`, `"views_per_visit"`, `"bounce_rate"`, `"visit_duration"`. |
| `realtimeFrom` | query | string (date-time) | No | Optional ISO timestamp used as the lower bound for realtime queries. |

### Responses

- `200`: Web traffic metrics and timeseries
- `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 |
| --- | --- | --- | --- |
| `metrics` | object \| null | Yes |  |
| `metrics.uniqueVisitors` | integer | Yes |  |
| `metrics.totalVisits` | integer | Yes |  |
| `metrics.pageviews` | integer | Yes |  |
| `metrics.viewsPerVisit` | number | Yes | Average pageviews per visit. |
| `metrics.bounceRate` | number | Yes | Percentage from 0 to 100 of visits with exactly one pageview. |
| `metrics.visitDuration` | number | Yes | Average visit duration in seconds. |
| `timeseries` | object[] \| null | Yes |  |
| `timeseries[].date` | string | Yes |  |
| `timeseries[].value` | number | Yes |  |
| `dataUpdatedAt` | string | Yes |  |

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

## GET /rest/v1/web-analytics/overview-insight

Read a fixed Overview report for up to 60 inclusive UTC days. TRAFFIC measures visitors with page views and page views; BEHAVIOR measures tracked clicks, dead clicks, and rage clicks. Both include web sources only and use the same counting and bot/test exclusions as Insights. Requires Analytics access and web-analytics:view; no custom-variable permission is required. Requires API-key scope or current OAuth user permission: web-analytics:view

Request URL: `GET https://app.oursprivacy.com/rest/v1/web-analytics/overview-insight`

Authentication: apiKey or oauth2.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `preset` | query | string | Yes | Built-in traffic or click-behavior report. Built-in traffic or click-behavior report. One of: `"TRAFFIC"`, `"BEHAVIOR"`. |
| `from` | query | string (date) | Yes | First included UTC calendar day (YYYY-MM-DD). First included UTC calendar day (YYYY-MM-DD). |
| `to` | query | string (date) | Yes | Last included UTC calendar day, at most 60 days including from. Last included UTC calendar day, at most 60 days including from. |

### Responses

- `200`: Built-in Overview report with daily values and full-range totals
- `400`: Invalid preset, dates, or a range longer than 60 inclusive days.
- `401`: Unauthorized — missing, invalid, or expired API key or OAuth access token
- `403`: Analytics access or web-analytics:view permission is missing.
- `404`: Not Found
- `500`: Internal Server Error

#### `200` response body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `semanticVersion` | number | Yes | One of: `1`. |
| `engine` | string | Yes | One of: `"clickhouse"`. |
| `sourcePolicy` | string | Yes |  |
| `sourceRevision` | string \| null | No |  |
| `sourceLimitations` | string[] | Yes |  |
| `scope` | object | Yes |  |
| `scope.from` | string | Yes |  |
| `scope.to` | string | Yes |  |
| `scope.interval` | string | Yes | One of: `"day"`, `"week"`, `"month"`. |
| `scope.timeZone` | string | Yes | One of: `"UTC"`. |
| `scope.sourceCompleteness` | string | Yes | One of: `"unknown"`. |
| `scope.executedAt` | string (date-time) | Yes |  |
| `scope.cumulative` | boolean | Yes |  |
| `scope.comparison` | object \| null | No |  |
| `scope.comparison.kind` | string | Yes | One of: `"previous_period"`, `"previous_year"`, `"custom"`. |
| `scope.comparison.from` | string | Yes |  |
| `scope.comparison.to` | string | Yes |  |
| `series` | object[] | Yes |  |
| `series[].key` | string | Yes |  |
| `series[].metricId` | string (uuid) | Yes |  |
| `series[].label` | string | Yes |  |
| `series[].breakdownValues` | object[] | Yes |  |
| `series[].breakdownValues[].property` | string | Yes |  |
| `series[].breakdownValues[].value` | string \| null | Yes |  |
| `series[].comparison` | string \| null | Yes | One of: `"previous_period"`, `"previous_year"`, `"custom"`, `null`. |
| `series[].aggregation` | string | Yes | One of: `"event_count"`, `"unique_visitors"`, `"sum"`, `"average"`. |
| `series[].points` | object[] | Yes |  |
| `series[].points[].bucketStart` | string (date-time) | Yes |  |
| `series[].points[].bucketEnd` | string (date-time) | Yes |  |
| `series[].points[].isPartial` | boolean | Yes |  |
| `series[].points[].raw` | number \| null | Yes |  |
| `series[].points[].smoothed` | number \| null | Yes |  |
| `series[].points[].cumulative` | number \| null | Yes |  |
| `series[].rangeValue` | number \| null | Yes |  |
| `reportId` | string \| null (uuid) | Yes | Saved report identifier; null for previews. |
| `revision` | string \| null (uuid) | Yes | Saved report revision; null for previews. |

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

## GET /rest/v1/web-analytics/sources

Return visitor counts grouped by referrer or UTM source dimension for the requested date range. Requires API-key scope or current OAuth user permission: web-analytics:view

Request URL: `GET https://app.oursprivacy.com/rest/v1/web-analytics/sources`

Authentication: apiKey or oauth2.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `from` | query | string (date) | Yes | Inclusive lower bound of the analysis window as `YYYY-MM-DD`. |
| `to` | query | string (date) | Yes | Inclusive upper bound of the analysis window as `YYYY-MM-DD`. |
| `webSourceId` | query | string (uuid) | No | Optional web source UUID. Omit to aggregate all web sources in the account. |
| `excludeBots` | query | boolean | No | Exclude detected bot sessions. Defaults to true. |
| `filters` | query | string | No | JSON-encoded query input. Optional JSON-encoded array of up to 20 filters. Dimensions: `page`, `entry_page`, `exit_page`, `source`, `medium`, `campaign`, `content`, `term`, `referrer`, `country`, `region`, `city`, `device`, `browser`, `os`. Each filter has a dimension, optional operator (`IS`, `IS_NOT`, `CONTAINS`, `NOT_CONTAINS`; defaults to `IS`), and one or more values. Example: `[{"dimension":"country","values":["United States"]}]`. |
| `dimension` | query | string | Yes | One of: `"referrer"`, `"campaign"`, `"source"`, `"medium"`, `"content"`, `"term"`. |

### Responses

- `200`: Traffic source breakdown
- `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 |
| --- | --- | --- | --- |
| `rows` | object[] | Yes |  |
| `rows[].name` | string | Yes |  |
| `rows[].visitors` | integer | Yes |  |
| `totalCount` | integer | Yes |  |
| `dataUpdatedAt` | string | Yes |  |

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

## GET /rest/v1/web-analytics/pages

Return page-level traffic metrics for top pages, entry pages, or exit pages in the requested date range. Requires API-key scope or current OAuth user permission: web-analytics:view

Request URL: `GET https://app.oursprivacy.com/rest/v1/web-analytics/pages`

Authentication: apiKey or oauth2.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `from` | query | string (date) | Yes | Inclusive lower bound of the analysis window as `YYYY-MM-DD`. |
| `to` | query | string (date) | Yes | Inclusive upper bound of the analysis window as `YYYY-MM-DD`. |
| `webSourceId` | query | string (uuid) | No | Optional web source UUID. Omit to aggregate all web sources in the account. |
| `excludeBots` | query | boolean | No | Exclude detected bot sessions. Defaults to true. |
| `filters` | query | string | No | JSON-encoded query input. Optional JSON-encoded array of up to 20 filters. Dimensions: `page`, `entry_page`, `exit_page`, `source`, `medium`, `campaign`, `content`, `term`, `referrer`, `country`, `region`, `city`, `device`, `browser`, `os`. Each filter has a dimension, optional operator (`IS`, `IS_NOT`, `CONTAINS`, `NOT_CONTAINS`; defaults to `IS`), and one or more values. Example: `[{"dimension":"country","values":["United States"]}]`. |
| `view` | query | string | Yes | One of: `"top"`, `"entry"`, `"exit"`. |

### Responses

- `200`: Top, entry, or exit page breakdown
- `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 |
| --- | --- | --- | --- |
| `rows` | object[] | Yes |  |
| `rows[].pageHostname` | string | Yes |  |
| `rows[].pagePath` | string | Yes |  |
| `rows[].pageviews` | integer \| null | Yes |  |
| `rows[].bounceRate` | number \| null | Yes | Percentage from 0 to 100 of visits to the page that bounced. |
| `rows[].timeOnPage` | number \| null | Yes | Average time on page in seconds when available. |
| `rows[].entries` | integer \| null | Yes |  |
| `rows[].visitors` | integer \| null | Yes |  |
| `rows[].exits` | integer \| null | Yes |  |
| `rows[].exitRate` | number \| null | Yes | Percentage from 0 to 100 of pageviews that ended a visit. |
| `totalCount` | integer | Yes |  |
| `dataUpdatedAt` | string | Yes |  |

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

## GET /rest/v1/web-analytics/locations

Return visitor counts grouped by country, region, or city for the requested date range. Requires API-key scope or current OAuth user permission: web-analytics:view

Request URL: `GET https://app.oursprivacy.com/rest/v1/web-analytics/locations`

Authentication: apiKey or oauth2.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `from` | query | string (date) | Yes | Inclusive lower bound of the analysis window as `YYYY-MM-DD`. |
| `to` | query | string (date) | Yes | Inclusive upper bound of the analysis window as `YYYY-MM-DD`. |
| `webSourceId` | query | string (uuid) | No | Optional web source UUID. Omit to aggregate all web sources in the account. |
| `excludeBots` | query | boolean | No | Exclude detected bot sessions. Defaults to true. |
| `filters` | query | string | No | JSON-encoded query input. Optional JSON-encoded array of up to 20 filters. Dimensions: `page`, `entry_page`, `exit_page`, `source`, `medium`, `campaign`, `content`, `term`, `referrer`, `country`, `region`, `city`, `device`, `browser`, `os`. Each filter has a dimension, optional operator (`IS`, `IS_NOT`, `CONTAINS`, `NOT_CONTAINS`; defaults to `IS`), and one or more values. Example: `[{"dimension":"country","values":["United States"]}]`. |
| `dimension` | query | string | Yes | One of: `"country"`, `"region"`, `"city"`. |

### Responses

- `200`: Visitor location breakdown
- `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 |
| --- | --- | --- | --- |
| `rows` | object[] | Yes |  |
| `rows[].name` | string | Yes |  |
| `rows[].code` | string \| null | Yes |  |
| `rows[].visitors` | integer | Yes |  |
| `totalCount` | integer | Yes |  |
| `dataUpdatedAt` | string | Yes |  |

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

## GET /rest/v1/web-analytics/devices

Return visitor counts grouped by device type, browser, or operating system for the requested date range. Requires API-key scope or current OAuth user permission: web-analytics:view

Request URL: `GET https://app.oursprivacy.com/rest/v1/web-analytics/devices`

Authentication: apiKey or oauth2.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `from` | query | string (date) | Yes | Inclusive lower bound of the analysis window as `YYYY-MM-DD`. |
| `to` | query | string (date) | Yes | Inclusive upper bound of the analysis window as `YYYY-MM-DD`. |
| `webSourceId` | query | string (uuid) | No | Optional web source UUID. Omit to aggregate all web sources in the account. |
| `excludeBots` | query | boolean | No | Exclude detected bot sessions. Defaults to true. |
| `filters` | query | string | No | JSON-encoded query input. Optional JSON-encoded array of up to 20 filters. Dimensions: `page`, `entry_page`, `exit_page`, `source`, `medium`, `campaign`, `content`, `term`, `referrer`, `country`, `region`, `city`, `device`, `browser`, `os`. Each filter has a dimension, optional operator (`IS`, `IS_NOT`, `CONTAINS`, `NOT_CONTAINS`; defaults to `IS`), and one or more values. Example: `[{"dimension":"country","values":["United States"]}]`. |
| `dimension` | query | string | Yes | One of: `"device"`, `"browser"`, `"os"`. |

### Responses

- `200`: Visitor device breakdown
- `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 |
| --- | --- | --- | --- |
| `rows` | object[] | Yes |  |
| `rows[].name` | string | Yes |  |
| `rows[].visitors` | integer | Yes |  |
| `totalCount` | integer | Yes |  |
| `dataUpdatedAt` | string | Yes |  |

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

## GET /rest/v1/web-analytics/current-visitors

Return the distinct visitors active in the most recent 15-minute window, optionally scoped to one web source. Requires API-key scope or current OAuth user permission: web-analytics:view

Request URL: `GET https://app.oursprivacy.com/rest/v1/web-analytics/current-visitors`

Authentication: apiKey or oauth2.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `webSourceId` | query | string (uuid) | No | Optional web source UUID. Omit to count visitors across all account web sources. |

### Responses

- `200`: Current visitor count
- `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 |
| --- | --- | --- | --- |
| `count` | integer | Yes |  |

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

## GET /rest/v1/web-analytics/path-explorer

Return the next or previous journey steps for a pinned path. The `path` and `filters` query parameters are JSON-encoded arrays. Requires API-key scope or current OAuth user permission: web-analytics:view

Request URL: `GET https://app.oursprivacy.com/rest/v1/web-analytics/path-explorer`

Authentication: apiKey or oauth2.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `from` | query | string (date) | Yes | Inclusive lower bound of the analysis window as `YYYY-MM-DD`. |
| `to` | query | string (date) | Yes | Inclusive upper bound of the analysis window as `YYYY-MM-DD`. |
| `webSourceId` | query | string (uuid) | No | Optional web source UUID. Omit to aggregate all web sources in the account. |
| `excludeBots` | query | boolean | No | Exclude detected bot sessions. Defaults to true. |
| `filters` | query | string | No | JSON-encoded query input. Optional JSON-encoded array of up to 20 cohort filters. Supports web analytics dimensions plus `event_name`, `ep_currency`, `ep_appointment_id`, `ep_appointment_status`, `ep_service_line`, `ep_provider_id`, `ep_location_id`, `ep_booking_channel`, `ep_revenue_type`, `ep_call_outcome`, and `ep_staff_id`. Each filter has a dimension, optional operator (`IS`, `IS_NOT`, `CONTAINS`, `NOT_CONTAINS`; defaults to `IS`), and one or more values. |
| `path` | query | string | Yes | JSON-encoded query input. JSON-encoded ordered path of opaque path explorer step keys. Use an empty array to request first-column candidates. |
| `direction` | query | string | No | One of: `"forward"`, `"reverse"`. |
| `stepKind` | query | string | No | One of: `"PAGE"`, `"EVENT"`. |
| `search` | query | string | No |  |
| `limit` | query | integer | No |  |

### Responses

- `200`: Path Explorer step distribution
- `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 |
| --- | --- | --- | --- |
| `anchorSessions` | integer | Yes |  |
| `steps` | object[] | Yes |  |
| `steps[].key` | string | Yes |  |
| `steps[].kind` | string \| null | Yes | One of: `"PAGE"`, `"EVENT"`, `null`. |
| `steps[].label` | string | Yes |  |
| `steps[].isTerminal` | boolean | Yes |  |
| `steps[].isOther` | boolean | Yes |  |
| `steps[].sessions` | integer | Yes |  |
| `hasMore` | boolean | Yes |  |

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

## GET /rest/v1/analytics/query-catalog

Discover the filter properties, operators, and providers available to analytics query definitions. Requires API-key scope or current OAuth user permission: variables:find-default

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

Authentication: apiKey or oauth2.

### Responses

- `200`: Analytics query filter catalog
- `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`. |
| `entries` | object[] | Yes |  |
| `entries[].id` | string | Yes |  |
| `entries[].label` | string | Yes |  |
| `entries[].type` | string | Yes |  |
| `entries[].operators` | string[] | Yes |  |
| `entries[].scope` | string | Yes |  |
| `entries[].provider` | string | Yes |  |
| `entries[].missingBehavior` | string | Yes |  |
| `entries[].requiresPath` | boolean \| null | No |  |
| `entries[].allowedTypes` | string[] \| null | No |  |
| `limitations` | string[] | Yes |  |

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

## GET /rest/v1/analytics/property-suggestions

Discover property paths recently observed in event data. Results are suggestions from a fixed recent 30-day sample and may be incomplete; callers can still use manually entered paths. Use `eventName` and `sourceId` to narrow the suggestions. Requires API-key scope or current OAuth user permission: variables:find-custom, web-analytics:view

Request URL: `GET https://app.oursprivacy.com/rest/v1/analytics/property-suggestions`

Authentication: apiKey or oauth2.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `eventName` | query | string | No | Optional exact event name to scope the suggestions. |
| `sourceId` | query | string | No | Optional exact source identifier to scope the suggestions. |

### Responses

- `200`: Recently observed analytics property suggestions
- `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 |
| --- | --- | --- | --- |
| `entities` | object[] | Yes |  |
| `entities[].property` | string | Yes | One of: `"event.properties"`, `"event.visitor_properties"`. |
| `entities[].path` | string[] | Yes |  |
| `entities[].type` | string | Yes | One of: `"string"`, `"number"`, `"boolean"`. |
| `sampled` | boolean | Yes |  |
| `from` | string (date-time) | Yes |  |
| `to` | string (date-time) | Yes |  |

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