# Session Replays

> List recorded session replay summaries and retrieve daily replay totals through the REST API.

Source: https://docs.oursprivacy.com/docs/platform-api/session-replays

List replay-bearing sessions for an inclusive calendar-day range. The list supports event, page, visitor, UTM, and explicit session-ID filters, and uses cursor pagination. The overview endpoint returns account-wide replay totals and a daily timeseries for the same date range.

## GET /rest/v1/session-replays

List recorded sessions for a date range. Filter by event, page, visitor, UTM fields, or an explicit JSON-encoded session ID list. Use `pagination.nextCursor` to retrieve the next page. Requires API-key scope or current OAuth user permission: web-analytics:view

Request URL: `GET https://app.oursprivacy.com/rest/v1/session-replays`

Authentication: apiKey or oauth2.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `from` | query | string (date) | Yes | Inclusive lower bound of the replay window as `YYYY-MM-DD`. |
| `to` | query | string (date) | Yes | Inclusive upper bound of the replay window as `YYYY-MM-DD`. |
| `filter` | query | string | No | JSON-encoded versioned analytics filter. Uses the shared analytics catalog property IDs and operators, including event, session, and custom properties. |
| `eventName` | query | string | No |  |
| `pathname` | query | string | No |  |
| `visitorId` | query | string | No |  |
| `utmSource` | query | string | No |  |
| `utmMedium` | query | string | No |  |
| `utmCampaign` | query | string | No |  |
| `utmContent` | query | string | No |  |
| `utmTerm` | query | string | No |  |
| `utmName` | query | string | No |  |
| `sessionIds` | query | string | No | Optional JSON-encoded session ID array. Maximum 100 session IDs. |
| `limit` | query | integer | No | Maximum replay sessions to return. Defaults to the report default. |
| `cursor` | query | string | No | Opaque pagination cursor from pagination.nextCursor in the previous response. Do not decode or modify it. Malformed cursors return 400 Bad Request. |

### Responses

- `200`: Session replay list
- `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 |
| --- | --- | --- | --- |
| `items` | object[] | Yes |  |
| `items[].sessionId` | string | Yes |  |
| `items[].visitorId` | string | Yes |  |
| `items[].date` | string | Yes |  |
| `items[].duration` | integer \| null | Yes |  |
| `items[].eventCount` | integer \| null | Yes |  |
| `items[].pageCount` | integer \| null | Yes |  |
| `items[].startTime` | string \| null | Yes |  |
| `pagination` | object | Yes |  |
| `pagination.nextCursor` | string \| null | No |  |
| `pagination.hasMore` | boolean | Yes |  |

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

## GET /rest/v1/session-replays/overview

Return the total number of replay-bearing sessions and a daily timeseries 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/session-replays/overview`

Authentication: apiKey or oauth2.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `from` | query | string (date) | Yes | Inclusive lower bound of the replay window as `YYYY-MM-DD`. |
| `to` | query | string (date) | Yes | Inclusive upper bound of the replay window as `YYYY-MM-DD`. |

### Responses

- `200`: Session replay totals and daily 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 |
| --- | --- | --- | --- |
| `totalReplays` | integer | Yes |  |
| `timeseries` | object[] | Yes |  |
| `timeseries[].date` | string | Yes |  |
| `timeseries[].value` | integer | Yes |  |

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