# Query Events

> Search, inspect, and export event occurrences through the Ours Privacy Platform API.

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

Use Query Events to search event occurrences with date, event, visitor, source, session, page, and property filters. JSON-encode the `input` object in the query string. Continue through results with `pagination.nextCursor` while `hasMore` is true.

The list returns event summaries and can include raw event or visitor properties. Use occurrence lookup to inspect an individual event or export up to 100 rows as CSV or JSON.

## GET /rest/v1/query-events

List matching event occurrences. JSON-encode input in the query string. includeCount defaults to false. Requests that include raw event or visitor properties also require event-detail permission, checked by the resolver; a missing permission is masked as 404 Not Found. Requires API-key scope or current OAuth user permission: report:list-events

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

Authentication: apiKey or oauth2.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `input` | query | string | Yes | Query Events filters and projection. JSON-encode input in the REST query string. Query Events filters and projection. JSON-encode input in the REST query string. |
| `limit` | query | integer | No |  |
| `cursor` | query | string | No | Cursor from the previous page. Cursor from the previous page. |
| `includeCount` | query | boolean | No |  |

### Responses

- `200`: Query Events page
- `400`: Invalid filters, date range, projection, or cursor.
- `401`: Unauthorized — missing, invalid, or expired API key or OAuth access token
- `403`: Event listing permission is missing.
- `404`: Not Found
- `500`: Internal Server Error

#### `200` response body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `rows` | object[] | Yes |  |
| `rows[].cursor` | string | Yes |  |
| `rows[].timestamp` | string (date-time) | Yes |  |
| `rows[].eventName` | string | Yes |  |
| `rows[].visitorId` | string | Yes |  |
| `rows[].distinctId` | string | Yes |  |
| `rows[].sourceId` | string | Yes |  |
| `rows[].sourceName` | string | Yes |  |
| `rows[].sourceType` | string | Yes |  |
| `rows[].isTestEvent` | boolean | Yes |  |
| `rows[].isBot` | boolean | Yes |  |
| `rows[].sessionId` | string \| null | Yes |  |
| `rows[].pagePath` | string \| null | Yes |  |
| `rows[].email` | string \| null | Yes |  |
| `rows[].eventProperties` | object | Yes |  |
| `rows[].visitorProperties` | object | Yes |  |
| `rows[].columns` | object[] | Yes |  |
| `rows[].columns[].property` | string | Yes |  |
| `rows[].columns[].path` | string[] \| null | Yes |  |
| `rows[].columns[].type` | string \| null | Yes | One of: `"STRING"`, `"NUMBER"`, `"BOOLEAN"`, `null`. |
| `rows[].columns[].value` | string \| null | Yes |  |
| `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-events/capabilities

Return Query Events date, page, selection, projection, and export limits. Requires API-key scope or current OAuth user permission: report:list-events

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

Authentication: apiKey or oauth2.

### Responses

- `200`: Query Events 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` | integer | Yes |  |
| `maxPageSize` | number | Yes | One of: `250`. |
| `maxDateRangeDays` | number | Yes | One of: `366`. |
| `maxSelections` | number | Yes | One of: `10`. |
| `maxColumns` | number | Yes | One of: `20`. |
| `maxExportRows` | number | Yes | One of: `100`. |
| `supportsVerifiedCoverageWatermark` | boolean | Yes |  |

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

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

List the filter fields and operators supported by Query Events. Requires API-key scope or current OAuth user permission: report:list-events

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

Authentication: apiKey or oauth2.

### Responses

- `200`: Analytics 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 | Catalog format version. One of: `1`. |
| `entries` | object[] | Yes | Fields available to analytics report filters. |
| `entries[].id` | string | Yes | Catalog identifier for this filterable field. |
| `entries[].label` | string | Yes | Human-readable field name. |
| `entries[].type` | string | Yes | Value type the filter compares against. |
| `entries[].operators` | string[] | Yes | Operators this field accepts in a filter condition. |
| `entries[].scope` | string | Yes | Whether the field belongs to the event or to its session. |
| `entries[].provider` | string | Yes | Data source that supplies the field value. |
| `entries[].missingBehavior` | string | Yes | How a filter treats events where the field is absent. |
| `entries[].requiresPath` | boolean \| null | No | True when a property path must be supplied, as for custom event properties. |
| `entries[].allowedTypes` | string[] \| null | No | Value types allowed for a path-based field. |
| `limitations` | string[] | Yes | Known limits of analytics filtering. |

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

## GET /rest/v1/query-events/property-suggestions

Suggest observed event and visitor property paths. Optionally scope by exact event name or source id. Requires API-key scope or current OAuth user permission: report:list-events

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

Authentication: apiKey or oauth2.

### Parameters

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

### Responses

- `200`: Query Events 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 | Property paths and value types observed in a sample of recent events. |
| `entities[].property` | string | Yes | Property bag the path belongs to. One of: `"event.properties"`, `"event.visitor_properties"`. |
| `entities[].path` | string[] | Yes | Property path segments, outermost first. |
| `entities[].type` | string | Yes | Value type observed at this path. One of: `"string"`, `"number"`, `"boolean"`. |
| `sampled` | boolean | Yes | True when the suggestions come from a sample, so some paths may be missing. |
| `from` | string (date-time) | Yes | Start of the observation window the suggestions were drawn from. |
| `to` | string (date-time) | Yes | End of the observation window the suggestions were drawn from. |

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

## GET /rest/v1/query-events/event-names

List observed event names available to Query Events. Requires API-key scope or current OAuth user permission: report:list-events

Request URL: `GET https://app.oursprivacy.com/rest/v1/query-events/event-names`

Authentication: apiKey or oauth2.

### Responses

- `200`: Query Events event-name 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 | Distinct event names seen in the last 30 days, alphabetical. Not paginated: the list holds up to the 500 most frequent names. |
| `entities[].name` | string | Yes | Event name exactly as collected, including `$`-prefixed system events. |
| `sampled` | boolean | Yes | True when rare names may be missing from the list. Missing names still work when entered exactly. |
| `from` | string (date-time) | Yes | Start of the observation window the suggestions were drawn from. |
| `to` | string (date-time) | Yes | End of the observation window the suggestions were drawn from. |

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

## GET /rest/v1/query-events/occurrence

Find one event occurrence using the same JSON-encoded input and cursor returned by a Query Events list. Requires API-key scope or current OAuth user permission: report:list-events, report:view-event

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

Authentication: apiKey or oauth2.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `input` | query | string | Yes | The same filters used to obtain the event cursor. JSON-encode input in the REST query string. The same filters used to obtain the event cursor. JSON-encode input in the REST query string. |
| `cursor` | query | string | Yes | Cursor from the page containing this event. Cursor from the page containing this event. |

### Responses

- `200`: Event occurrence
- `400`: Bad Request
- `401`: Unauthorized — missing, invalid, or expired API key or OAuth access token
- `403`: Event listing and event-detail permissions are required.
- `404`: Not Found
- `500`: Internal Server Error

#### `200` response body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `cursor` | string | Yes |  |
| `timestamp` | string (date-time) | Yes |  |
| `eventName` | string | Yes |  |
| `visitorId` | string | Yes |  |
| `distinctId` | string | Yes |  |
| `sourceId` | string | Yes |  |
| `sourceName` | string | Yes |  |
| `sourceType` | string | Yes |  |
| `isTestEvent` | boolean | Yes |  |
| `isBot` | boolean | Yes |  |
| `sessionId` | string \| null | Yes |  |
| `pagePath` | string \| null | Yes |  |
| `email` | string \| null | Yes |  |
| `eventProperties` | object | Yes |  |
| `visitorProperties` | object | Yes |  |
| `columns` | object[] | Yes |  |
| `columns[].property` | string | Yes |  |
| `columns[].path` | string[] \| null | Yes |  |
| `columns[].type` | string \| null | Yes | One of: `"STRING"`, `"NUMBER"`, `"BOOLEAN"`, `null`. |
| `columns[].value` | string \| null | Yes |  |

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

## GET /rest/v1/query-events/export

Export matching events as CSV or JSON, up to the supported row limit. JSON-encode input in the query string. Requires API-key scope or current OAuth user permission: report:list-events, report:view-event

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

Authentication: apiKey or oauth2.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `input` | query | string | Yes | Query Events filters and projection. JSON-encode input in the REST query string. Query Events filters and projection. JSON-encode input in the REST query string. |
| `format` | query | string | Yes | Export encoding. Export encoding. One of: `"CSV"`, `"JSON"`. |
| `cursor` | query | string | No | Start after this event cursor. Start after this event cursor. |
| `limit` | query | integer | No |  |

### Responses

- `200`: Query Events export
- `400`: Bad Request
- `401`: Unauthorized — missing, invalid, or expired API key or OAuth access token
- `403`: Event listing and event-detail permissions are required.
- `404`: Not Found
- `500`: Internal Server Error

#### `200` response body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `content` | string | Yes |  |
| `rowCount` | integer | Yes |  |
| `format` | string | Yes | One of: `"CSV"`, `"JSON"`. |
| `pagination` | object | Yes |  |
| `pagination.hasMore` | boolean | Yes |  |
| `pagination.nextCursor` | string \| null | Yes |  |

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

## Next Steps

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