Read events
GET /api/v0/events returns the events of your shop, newest first, 10 per page.
When to use it
Section titled “When to use it”Use it when you want Releva’s event log in your own systems. To look at one customer’s events, or to export events to a file, the admin is quicker: see Export events to a file.
Authentication
Section titled “Authentication”Send your shop’s Secret Key as a bearer token: authorization: Bearer $RELEVA_SECRET_KEY. Find it under Settings › Shop & Integration (Find your Access Token and Secret Key). The error messages are in Events API: Authentication.
Request
Section titled “Request”GET https://releva.ai/api/v0/events. All query parameters are optional.
| Parameter | Notes |
|---|---|
eventTypes[] |
One or more actions, for example the default event types pageView, cartAdd and cartCheckoutSuccess, or your custom actions. Use the array syntax: eventTypes[]=a&eventTypes[]=b. Unknown actions return {"events":[]}. |
startDateTime |
ISO-8601 with seconds and a zone. Inclusive. Percent-encode : and + (%2B); an unencoded + becomes a space and answers 400. |
endDateTime |
Same format. Exclusive: an event at exactly this time is not returned. |
cursor |
The nextCursor of the previous page. |
curl 'https://releva.ai/api/v0/events?eventTypes%5B%5D=giftCardRedeemed&startDateTime=2026-10-21T00%3A00%3A00Z' \ -H "authorization: Bearer $RELEVA_SECRET_KEY" \ -H 'content-type: application/json'With every parameter, for the next page of browser events in a time window:
curl -G 'https://releva.ai/api/v0/events' \ -H "authorization: Bearer $RELEVA_SECRET_KEY" \ -H 'content-type: application/json' \ --data-urlencode 'eventTypes[]=pageView' \ --data-urlencode 'eventTypes[]=cartAdd' \ --data-urlencode 'eventTypes[]=cartCheckoutSuccess' \ --data-urlencode 'startDateTime=2026-10-21T00:00:00Z' \ --data-urlencode 'endDateTime=2026-10-22T00:00:00Z' \ --data-urlencode 'cursor=<nextCursor from the previous page>'Response
Section titled “Response”200 with events (at most 10) and, when the page is full, a nextCursor string to pass as cursor on the next call. One event, as returned by the request above (profile trimmed):
{ "events": [ { "userAgent": {}, "profileId": "profile/15/DEMO-CUST-1001", "domainId": "15", "action": "giftCardRedeemed", "timestamp": "2026-10-20T21:55:25.013Z", "locale": "en", "location": [0, 0], "products": [ { "available": true, "categories": ["Men/Shirts", "Summer"], "currency": "EUR", "id": "DEMO-1001", "locale": "en", "name": "Linen Summer Shirt", "price": 39.9, "priceTotalInDomainCurrency": 39.9, "quantity": 1, "sku": "DEMO-1001-M", "custom": { "string": [ { "key": "brand", "values": ["Demo Basics"] }, { "key": "color", "values": ["white", "sand"] }, { "key": "category_level_1", "values": ["Men", "Summer"] }, { "key": "category_level_2", "values": ["Shirts"] } ], "numeric": [], "date": [] } } ], "cartTotalInDomainCurrency": 39.9, "ingestedAt": "2026-10-20 21:55:28.000", "custom": { "string": [{ "key": "cardType", "values": ["digital"] }], "numeric": [], "date": [] }, "profile": { "id": "profile/15/DEMO-CUST-1001", "email": "maria@example.com", "firstName": "Maria", "lastName": "Example" }, "id": "profile/15/DEMO-CUST-1001" } ]}About the response:
profileIdandidhave the formprofile/<domainId>/<profile id>.profilecarries the full stored profile (consent, subscriptions, tags, custom fields and internal flags). It is missing when the profile no longer exists. The example above is trimmed.- Search events carry
filteras a JSON string. Events from the SDK also carryurl,ip,groupAssignmentand, when sent,sessionId,deviceIdandpageToken. Server events have an emptyuserAgent. ingestedAtis UTC without a zone marker.nextCursoris present only when the page holds 10 events. The last page has none, and it can be an empty page when the total is a multiple of 10.
Known issue. Events inside one page are not guaranteed to be in timestamp order, and nextCursor is built from the last event of the page as returned rather than the oldest. Pages can therefore repeat an event, and in rare cases skip one. Until this is fixed, de-duplicate by id, action and timestamp across pages and sort on your side.
Errors
Section titled “Errors”| Status | When | Message |
|---|---|---|
400 |
Authentication failed | See Events API: Authentication |
400 |
eventTypes=a without [] |
The 'eventTypes' field must be an array. |
402 |
Your shop is disabled | Domain is disabled. Please reach out to support@releva.ai to enable it. |
500 |
An invalid cursor, or an unexpected error |
An internal error occurred. |
Limits
Section titled “Limits”- At most 10 events per call.
- Rate limits: none.