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.

The response contains entities and pagination, with nextCursor and hasMore. The optional limit defaults to 25 and is clamped to 1–100. Pass pagination.nextCursor as cursor to retrieve the next page.

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. A missing event, an event that has not arrived yet, or an event outside the 48-hour window returns 404.

Send and inspect dispatches

POST /rest/v1/test-events acknowledges the event and returns an id, visitorId, and distinctId. It does not return processing results. An optional sourceId must be a UUID identifying an enabled source that accepts API events.

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. The collection is empty until dispatch records arrive and can grow as processing continues. It may remain empty when no dispatch occurs. An empty collection does not identify a cause, and this endpoint does not predict destinations or signal that processing is complete.

Synthetic events sent through this API enable debug capture automatically and appear in Recent Events. Both the UI and this endpoint show recorded dispatches only.

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. Unknown fields, including url, are ignored; put custom event data in eventProperties.

Scopes

Read scopes are granted separately because event and dispatch properties can contain personal information. An API key with only test-event:create cannot read captured events or dispatch results.

Identity

visitorId and distinctId are optional; omitted values are generated and returned in the response. For synthetic sends, both are limited to 1–128 letters, numbers, hyphens, or underscores. Browser and server identifiers may contain other characters; the list returns an encoded id when needed. Treat returned IDs as opaque and pass them unchanged to the read endpoints.

All reads are restricted to debug-captured events and dispatches belonging to your account. Debug capture does not change delivery: browser and server events using live tokens can still reach destinations. Events created by POST /rest/v1/test-events use the source’s live token and have isTestEvent: false.

Sources that restrict events by IP address

A source configured with an IP allow list cannot accept test events, and POST /rest/v1/test-events returns 409 for it. Test events are sent from the API rather than from a browser or device, so there is no originating address for the allow list to match. Sources without an IP allow list can accept test events.

curl -X POST "https://example.com/rest/v1/test-events" \  -H "Content-Type: application/json" \  -d '{    "eventName": "Purchase"  }'

{  "id": "a1b2c3d4:ck9x8y7z6w5v4u3t",  "visitorId": "string",  "distinctId": "string",  "eventName": "string",  "sourceId": "string",  "acceptedAt": "string"}

curl -X GET "https://example.com/rest/v1/test-events"

{  "entities": [    {      "id": "string",      "visitorId": "string",      "distinctId": "string",      "eventName": "string",      "time": "string",      "sourceId": "string",      "sourceName": "string",      "sourceType": "string",      "isTestEvent": true,      "eventProperties": {},      "userProperties": {},      "defaultProperties": {},      "requestContext": {},      "rawData": "string"    }  ],  "pagination": {    "nextCursor": "string",    "hasMore": true  }}

curl -X GET "https://example.com/rest/v1/test-events/a1b2c3d4:ck9x8y7z6w5v4u3t"

{  "id": "string",  "visitorId": "string",  "distinctId": "string",  "eventName": "string",  "time": "string",  "sourceId": "string",  "sourceName": "string",  "sourceType": "string",  "isTestEvent": true,  "eventProperties": {},  "userProperties": {},  "defaultProperties": {},  "requestContext": {},  "rawData": "string"}

curl -X GET "https://example.com/rest/v1/test-events/a1b2c3d4:ck9x8y7z6w5v4u3t/dispatches"

{  "id": "string",  "entities": [    {      "destinationId": "string",      "destinationName": "string",      "destinationType": "string",      "allowedEventId": "string",      "allowedEventName": "string",      "dispatchedAt": "string",      "dispatchedSuccessAt": "string",      "success": true,      "message": "string",      "payload": {}    }  ]}