# Read events

> GET /api/v0/events: read your shop's events, newest first, 10 per page, with the query parameters, paging, a working curl, the response and errors.

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

## 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](https://releva.ai/documentation/guides/events/export-events/).

## 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](https://releva.ai/documentation/guides/shop-settings/find-your-api-keys/)). The error messages are in [Events API: Authentication](https://releva.ai/documentation/reference/events/overview/#authentication).

## 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.                                                                                                                                                                                           |

```plaintext
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:

```plaintext
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

`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):

```plaintext
{
  "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.

## Errors

| Status | When                                        | Message                                                                                    |
| ------ | ------------------------------------------- | ------------------------------------------------------------------------------------------ |
| `400`  | Authentication failed                       | See [Events API: Authentication](https://releva.ai/documentation/reference/events/overview/#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

* At most 10 events per call.
* Rate limits: none.

## Next steps

* [Send custom events](https://releva.ai/documentation/reference/events/send-custom-events/): Record the events from your backend that you then read back.
* [Export events to a file](https://releva.ai/documentation/guides/events/export-events/): Filter events in the admin and receive them as a file by email.
* [See all events of a customer](https://releva.ai/documentation/guides/events/see-all-events-of-a-customer/): Check one customer’s events in the admin.