# Test Events

> List and inspect debug-captured events from your website or server, send synthetic test events, and inspect recorded dispatches.

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

List and inspect debug-captured events from your website or server, send synthetic test events, and inspect recorded dispatches.

Events created through this API use the source’s live token with debug capture enabled. They follow your production event names, data governance rules, and mappings, and can deliver real data to configured destinations. Inspect the recorded dispatch payloads and results to verify delivery.

## List and retrieve captured events

`GET /rest/v1/test-events` lists browser, server, and synthetic events captured with debug mode during the last 48 hours, newest received first. Events sent with a live token are included when debug capture is enabled. `isTestEvent` distinguishes test-token events from live-token events.

`GET /rest/v1/test-events/{id}` returns the captured event’s name, timestamp, visitor and event identifiers, source, event properties, user properties, default properties, request context, and raw data when available. Use the `id` returned by the create or list endpoint unchanged. An event that has not arrived yet returns 404 until it does.

## Send and inspect dispatches

`POST /rest/v1/test-events` acknowledges the event and returns an `id`, `visitorId`, and `distinctId`. Processing results arrive on the dispatches endpoint.

`GET /rest/v1/test-events/{id}/dispatches` accepts an `id` from the create or list endpoint and returns `{ id, entities }`. Each entity is a recorded dispatch with its destination, mapped payload, and recorded success or failure details. Browser and server events captured in debug mode are included.

Processing is asynchronous, so the collection fills as dispatch records arrive and stays empty when nothing dispatches.

Synthetic events sent through this API enable debug capture automatically and appear in [Recent Events](https://app.oursprivacy.com/recent-events).

## Context properties

`defaultProperties` uses the same known context fields as the ingest API. Use `current_url` for the page URL, `referrer` for the referring URL, and fields such as `utm_source`, `user_agent`, and `screen_width` for attribution and browser context. The request schema below lists all supported fields. Put custom event data in `eventProperties`.

## Identity

`visitorId` and `distinctId` are optional; omitted values are generated and returned in the response. The list returns an encoded `id` when a browser or server identifier needs one, so treat returned IDs as opaque and pass them unchanged to the read endpoints.

Events created by `POST /rest/v1/test-events` use the source’s live token and have `isTestEvent: false`.

## POST /rest/v1/test-events

Send a test event through the same processing your production events go through, using the source’s live token with debug capture enabled. This can deliver real data to configured destinations. The response acknowledges acceptance for processing; it does not contain processing results. The event is captured in Recent Events. Use the returned `id` with `GET /rest/v1/test-events/{id}/dispatches` to retrieve recorded dispatches. Supply `visitorId` and `distinctId` to choose the identity yourself; otherwise they are generated and returned. Requires API-key scope or current OAuth user permission: test-event:create

Request URL: `POST https://app.oursprivacy.com/rest/v1/test-events`

Authentication: apiKey or oauth2.

### Request body (`application/json`, required)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `eventName` | string | Yes | Name of the event to send, matching an event name configured on this account. |
| `sourceId` | string \| null (uuid) | No | Source to attribute the event to. Defaults to the account's first enabled source that accepts events over the API. |
| `visitorId` | string \| null | No | Visitor identity to send the event as. Generated when omitted. Letters, numbers, hyphens, and underscores only. |
| `distinctId` | string \| null | No | Event identity for this specific event. Generated when omitted. Letters, numbers, hyphens, and underscores only. |
| `eventProperties` | object \| null | No | Event-level properties available to destination mappings. |
| `userProperties` | object \| null | No | Person-level properties available to destination mappings. |
| `defaultProperties` | object \| null | No | Known context properties used by ingest and destination mappings. Use current_url for the page URL. Unknown properties are ignored. |
| `defaultProperties.is_bot` | boolean \| null | No | Whether we have detected that the user is a bot. This is set automatically by the Ours server primarily for events tracked through the web SDK. |
| `defaultProperties.ad_id` | string \| null | No | The ad id detected in the session. This is set by the web sdk automatically. |
| `defaultProperties.adset_id` | string \| null | No | The adset id detected in the session. This is set by the web sdk automatically. |
| `defaultProperties.campaign_id` | string \| null | No | The campaign id detected in the session. This is set by the web sdk automatically. |
| `defaultProperties.alart` | string \| null | No | The AppLovin alart query parameter. Ex: alart123 |
| `defaultProperties.aleid` | string \| null | No | The AppLovin aleid query parameter. Ex: aleid123 |
| `defaultProperties.axwrt` | string \| null | No | The AppLovin pixel cookie value (_axwrt). Web-only. |
| `defaultProperties.affiliatly_v3` | string \| null | No | The raw Affiliatly tracking cookie value (affiliatly_v3), set by the Affiliatly script when a visitor lands from an affiliate link. Web-only. Ex: id_hash=abc&id_user=123&aff_uid=45 |
| `defaultProperties.encoding` | string \| null | No | The browser's encoding. Ex: UTF-8 |
| `defaultProperties.browser_name` | string \| null | No | The name of the browser. Ex: Chrome |
| `defaultProperties.browser_version` | string \| null | No | The version of the browser. Ex: 114.0 |
| `defaultProperties.cpu_architecture` | string \| null | No | The architecture of the CPU. Ex: amd64 |
| `defaultProperties.device_type` | string \| null | No | The type of device the user is using. Ex: mobile |
| `defaultProperties.device_model` | string \| null | No | The model of the device. Ex: iPhone |
| `defaultProperties.device_vendor` | string \| null | No | The vendor of the device. Ex: Apple |
| `defaultProperties.engine_name` | string \| null | No | The name of the browser engine. Ex: Blink |
| `defaultProperties.engine_version` | string \| null | No | The version of the browser engine. Ex: 114.0 |
| `defaultProperties.os_name` | string \| null | No | The name of the operating system. Ex: Windows |
| `defaultProperties.os_version` | string \| null | No | The version of the operating system. Ex: 10.0 |
| `defaultProperties.browser_language` | string \| null | No | The language of the browser, lowercased. Ex: en-us |
| `defaultProperties.current_url` | string \| null | No | The full url (including query params) of the current page |
| `defaultProperties.webview` | boolean \| null | No | Whether the user is in a webview. Ex: true |
| `defaultProperties.iframe` | boolean \| null | No | Whether the user is in an iframe. Ex: true |
| `defaultProperties.sessionCount` | number \| null | No | The number of sessions the user has had. Ex: 3 |
| `defaultProperties.activeDuration` | number \| null | No | The total time in milliseconds this tab has been visible since the page loaded |
| `defaultProperties.duration` | number \| null | No | The time in milliseconds since the previous event on this page, or since the web SDK loaded for the first event. Restarts when a hidden tab becomes visible again. |
| `defaultProperties.epik` | string \| null | No | The Pinterest Click ID. Ex: epik456 |
| `defaultProperties.sacid` | string \| null | No | The StackAdapt Tracking ID. Ex: sacid123 |
| `defaultProperties.ylpcid` | string \| null | No | The Yelp Click ID from the landing URL, sent unchanged and unhashed. |
| `defaultProperties.adct` | string \| null | No | The AdRoll Click ID (adct) from the landing URL. Ex: adct123 |
| `defaultProperties.basis_cid` | string \| null | No | The Basis DSP Click ID. Ex: basis_cid123 |
| `defaultProperties.ob_click_id` | string \| null | No | The Outbrain click ID, captured from the `ob_click_id` URL parameter (Outbrain `{{ob_click_id}}` macro) on the landing page. Ex: ob_click_abc123 |
| `defaultProperties.grclid` | string \| null | No | The Gravity click ID, captured from the `grclid` URL parameter that Gravity (trygravity.com) appends to ad click-through URLs on the landing page. Ex: grclid-abc123 |
| `defaultProperties.graid` | string \| null | No | The Gravity attribution ID, captured from the `graid` URL parameter on the landing page. Gravity resolves it to the campaign, publisher, and ad IDs server-side. Ex: graid-abc123 |
| `defaultProperties.beeswax_auction_id` | string \| null | No | The Beeswax (FreeWheel Buyer Cloud) auction ID, captured from the `{{AUCTION_ID}}` macro on creative click URLs. Ex: bx-auc-abc123 |
| `defaultProperties.admitad_uid` | string \| null | No | The Admitad (Mitgo) affiliate Click ID. Ex: admitad_uid_abc123 |
| `defaultProperties._ef_transaction_id` | string \| null | No | The Everflow affiliate Click (Transaction) ID, captured from the `_ef_transaction_id` URL parameter. Ex: ef_click_abc123 |
| `defaultProperties.viant_click_id` | string \| null | No | The Viant (Adelphic) Click ID, captured from the `viant_click_id` URL parameter (Viant `${ADELPHIC_CLICKID}` macro). Sent as `xid` on Viant postbacks. Ex: viant_click_abc123 |
| `defaultProperties.ttd_impression_id` | string \| null | No | The Trade Desk impression ID, captured from a configured ttd_impression_id URL parameter using the %%TTD_IMPRESSIONID%% creative macro. Sent as imp on conversions. |
| `defaultProperties.viant_impression_id` | string \| null | No | The Viant (Adelphic) Impression ID, captured from the `viant_impression_id` URL parameter (Viant `${ADELPHIC_IMPRESSIONID}` macro). Sent as `imp_id` on Viant postbacks for post-view attribution. Ex: viant_imp_abc123 |
| `defaultProperties.fbc` | string \| null | No | Facebook Click ID with prefix format for Conversions API tracking. Ex: fb.1.1554763741205.AbCdEfGhIjKlMnOpQrStUvWxYz1234567890 |
| `defaultProperties.fbclid` | string \| null | No | Raw Facebook Click ID query parameter without prefix from ad clicks. Ex: AbCdEfGhIjKlMnOpQrStUvWxYz1234567890 |
| `defaultProperties.fbp` | string \| null | No | Facebook Browser ID parameter for identifying browsers and attributing events. Ex: fb.1.1554763741205.1098115397 |
| `defaultProperties.gad_source` | string \| null | No | The Google Ad Source. Ex: google |
| `defaultProperties.gbraid` | string \| null | No | The Google Braid ID. Ex: gbraid123 |
| `defaultProperties.gclid` | string \| null | No | The Google Click ID. Ex: gclid123 |
| `defaultProperties.ndclid` | string \| null | No | The NextDoor Click ID. Ex: ndclid123 |
| `defaultProperties.oppref` | string \| null | No | The OpenAI Ads privacy-preserving reference, captured from the `oppref` URL parameter on landing pages (the OpenAI Pixel also stores it in a `__oppref` cookie). Sent to OpenAI Ads on Conversions API events for attribution. Ex: oppref_abc |
| `defaultProperties.dclid` | string \| null | No | The DoubleClick Click ID. Ex: dclid123 |
| `defaultProperties.qclid` | string \| null | No | The Quora Click ID. Ex: qclid123 |
| `defaultProperties.rdt_cid` | string \| null | No | The Reddit Click ID. Ex: rdt_cid123 |
| `defaultProperties.host` | string \| null | No | The host of the current page. Ex: example.com |
| `defaultProperties.ip` | string \| null | No | The IP address of the user. Ex: 127.0.0.1 |
| `defaultProperties.msclkid` | string \| null | No | The Microsoft Click ID. Ex: msclkid123 |
| `defaultProperties.li_fat_id` | string \| null | No | The LinkedIn Click ID. Ex: li_fat_id123 |
| `defaultProperties.pathname` | string \| null | No | The pathname of the current page. Ex: /home |
| `defaultProperties.referrer` | string \| null | No | The referrer URL of the current page |
| `defaultProperties.referring_domain` | string \| null | No | The referring domain of the current page |
| `defaultProperties.screen_height` | number \| null | No | The height of the screen. Ex: 1080 |
| `defaultProperties.screen_width` | number \| null | No | The width of the screen. Ex: 1920 |
| `defaultProperties.title` | string \| null | No | The title of the current page |
| `defaultProperties.user_agent` | string \| null | No | The user agent of the browser |
| `defaultProperties.utm_campaign` | string \| null | No | The UTM Campaign. The web SDK automatically captures this from the query params. |
| `defaultProperties.utm_content` | string \| null | No | The UTM Content. The web SDK automatically captures this from the query params. |
| `defaultProperties.utm_medium` | string \| null | No | The UTM Medium. The web SDK automatically captures this from the query params. |
| `defaultProperties.utm_name` | string \| null | No | The UTM Name. The web SDK automatically captures this from the query params. |
| `defaultProperties.ttclid` | string \| null | No | The TikTok Click ID. Ex: ttclid123 |
| `defaultProperties.twclid` | string \| null | No | The Twitter Click ID. Ex: twclid123 |
| `defaultProperties.clickid` | string \| null | No | The Click ID. Ex: clickid123 |
| `defaultProperties.clid` | string \| null | No | The Generic Click ID. Ex: clid123 |
| `defaultProperties.sccid` | string \| null | No | The Snapchat Click ID. Ex: sccid123 |
| `defaultProperties.irclickid` | string \| null | No | The Impact Click ID. Ex: irclickid123 |
| `defaultProperties.im_ref` | string \| null | No | The Impact Click ID reference. Ex: im_ref123 |
| `defaultProperties.utm_source` | string \| null | No | The UTM Source. The web SDK automatically captures this from the query params. |
| `defaultProperties.utm_term` | string \| null | No | The UTM Term. The web SDK automatically captures this from the query params. |
| `defaultProperties.version` | string \| null | No | The SDK version (e.g., web SDK or ingest-sdk-* via generated SDK headers) |
| `defaultProperties.wbraid` | string \| null | No | The WBRAID Identifier. The web SDK automatically captures this from the query params. |
| `defaultProperties.uafvl` | string \| null | No | The browser brands and full versions from User-Agent Client Hints, as brand;version pairs separated by \|. |
| `defaultProperties.page_hash` | number \| null | No | A random set of numbers for the page load |
| `defaultProperties.sid` | string \| null | No | The session ID as assigned automatically by the web SDK. This is required for session replay |
| `defaultProperties.new_s` | boolean \| null | No | Deprecated |
| `defaultProperties.fv` | boolean \| null | No | Deprecated |
| `defaultProperties.sr` | string \| null | No | The screen resolution as width x height in pixels. Ex: 1920x1080 |
| `defaultProperties.received_at` | string \| null | No | The time an Ours server received the event, in ISO 8601 UTC |

### Responses

- `200`: The accepted test event and its read-back id
- `400`: Bad request — the event payload was rejected, `sourceId` was not a valid id, or `visitorId` / `distinctId` contained unsupported characters.
- `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 — `sourceId` does not exist in this account.
- `409`: Conflict — the chosen source cannot accept events over the API, restricts events by IP address, or the account has no enabled source that can.
- `500`: Internal Server Error

#### `200` response body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | Identifier to pass to the event detail or dispatch endpoint. |
| `visitorId` | string | Yes |  |
| `distinctId` | string | Yes |  |
| `eventName` | string | Yes |  |
| `sourceId` | string | Yes |  |
| `acceptedAt` | string | Yes | When the event was accepted for processing, as an ISO 8601 timestamp. |

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

## GET /rest/v1/test-events

List browser, server, and synthetic events captured with debug mode during the last 48 hours, newest received first. Includes live-token and test-token events; `isTestEvent` indicates whether a test token was used. Returns full event properties. Pass an entity id unchanged to the detail or dispatch endpoint. Use `limit` (default 25, maximum 100) and `cursor` to page through results. Requires API-key scope or current OAuth user permission: report:list-events

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

Authentication: apiKey or oauth2.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `limit` | query | integer \| null | No | Maximum number of items to return. Defaults to 25; values below 1 are clamped to 1 and values above 100 are clamped to 100. Maximum number of items to return. Defaults to 25; values below 1 are clamped to 1 and values above 100 are clamped to 100. |
| `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. Opaque pagination cursor from pagination.nextCursor in the previous response. Do not decode or modify it. Malformed cursors return 400 Bad Request. |

### Responses

- `200`: Debug-captured events and cursor pagination
- `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[].id` | string | Yes |  |
| `entities[].visitorId` | string | Yes |  |
| `entities[].distinctId` | string | Yes |  |
| `entities[].eventName` | string | Yes |  |
| `entities[].time` | string | Yes |  |
| `entities[].sourceId` | string \| null | No |  |
| `entities[].sourceName` | string \| null | No |  |
| `entities[].sourceType` | string \| null | No |  |
| `entities[].isTestEvent` | boolean | Yes | Whether the event used a test token. Debug-captured live-token events have false here. |
| `entities[].eventProperties` | object \| null | No |  |
| `entities[].userProperties` | object \| null | No |  |
| `entities[].defaultProperties` | object \| null | No |  |
| `entities[].requestContext` | object \| null | No |  |
| `entities[].rawData` | string \| null | No |  |
| `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/test-events/{id}

Retrieve one browser, server, or synthetic event captured in debug mode within the last 48 hours. Use an id returned by the create or list endpoint. Events that have not arrived, expired events, and events outside your account return 404. Requires API-key scope or current OAuth user permission: report:view-event

Request URL: `GET https://app.oursprivacy.com/rest/v1/test-events/{id}`

Authentication: apiKey or oauth2.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | Yes | Event id returned by the create or list endpoint. Pass it unchanged; it may be an opaque encoded value. |

### Responses

- `200`: The captured event, including its original properties and source
- `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 |
| --- | --- | --- | --- |
| `id` | string | Yes |  |
| `visitorId` | string | Yes |  |
| `distinctId` | string | Yes |  |
| `eventName` | string | Yes |  |
| `time` | string | Yes |  |
| `sourceId` | string \| null | No |  |
| `sourceName` | string \| null | No |  |
| `sourceType` | string \| null | No |  |
| `isTestEvent` | boolean | Yes | Whether the event used a test token. Debug-captured live-token events have false here. |
| `eventProperties` | object \| null | No |  |
| `userProperties` | object \| null | No |  |
| `defaultProperties` | object \| null | No |  |
| `requestContext` | object \| null | No |  |
| `rawData` | string \| null | No |  |

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

## GET /rest/v1/test-events/{id}/dispatches

Retrieve dispatches recorded for a debug-captured browser, server, or synthetic event. Use an id returned by the create or list endpoint. The entities array contains mapped payloads and recorded success or failure details. It is empty until dispatch records arrive, and may remain empty when no dispatch occurs. Results can grow as processing continues; this endpoint does not predict destinations or signal completion. Requires the report:view-dispatch scope. Requires API-key scope or current OAuth user permission: report:view-dispatch

Request URL: `GET https://app.oursprivacy.com/rest/v1/test-events/{id}/dispatches`

Authentication: apiKey or oauth2.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | Yes | Event id returned by the create or list endpoint. Pass it unchanged; it may be an opaque encoded value. |

### Responses

- `200`: Recorded dispatches for the debug event
- `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 |
| --- | --- | --- | --- |
| `id` | string | Yes |  |
| `entities` | object[] | Yes | Dispatches recorded so far. Empty until dispatches arrive; no predicted destinations or completion signal. Events created through this API can be delivered to live destinations. |
| `entities[].destinationId` | string | Yes |  |
| `entities[].destinationName` | string \| null | No |  |
| `entities[].destinationType` | string \| null | No |  |
| `entities[].allowedEventId` | string \| null | No |  |
| `entities[].allowedEventName` | string \| null | No |  |
| `entities[].dispatchedAt` | string \| null | No | When the send was attempted, as an ISO 8601 timestamp. |
| `entities[].dispatchedSuccessAt` | string \| null | No | When the destination accepted the send, as an ISO 8601 timestamp. |
| `entities[].success` | boolean \| null | No | Whether this send succeeded. Null while the attempt is still in flight. |
| `entities[].message` | string \| null | No | Failure detail when `success` is false. |
| `entities[].payload` | object \| null | No | The mapped payload recorded for this dispatch. |

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