Skip to content

Area: Developers

Read events

GET /api/v0/events returns the events of your shop, newest first, 10 per page.

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.

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.

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>'

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:

  • profileId and id have the form profile/<domainId>/<profile id>.
  • profile carries 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 filter as a JSON string. Events from the SDK also carry url, ip, groupAssignment and, when sent, sessionId, deviceId and pageToken. Server events have an empty userAgent.
  • ingestedAt is UTC without a zone marker.
  • nextCursor is 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.

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.
  • At most 10 events per call.
  • Rate limits: none.