Test Events

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

Synthetic test events use the same event names, data governance rules, and mappings as your production events, so a test event routed to a destination with the payload you expect confirms that configuration is correct. Nothing is delivered to the destination itself, so a test event confirms your configuration rather than the destination's own acceptance of the data.

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.

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. Synthetic events created by POST /rest/v1/test-events always use a test token.

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": {}    }  ]}