> ## Documentation Index
> Fetch the complete documentation index at: https://client-integrations-api-dev.sequen.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Events
An event is any client-side or server-side action a visitor takes on your site or app—page loads, impressions, clicks, check-outs, dwell time, and more. Capturing these signals fuels our behaviour-based ranking engine and lets us update recommendations in real time.
## Why send rich event data?
Our pipeline automatically hunts for the most predictive features, so the more properties you include, the stronger the model becomes. Don’t worry about over-engineering the schema up front—just send what you have and the platform will do feature selection for you. Rich, well-linked behavioural data is how we unlock advanced capabilities such as dynamic re-ranking and session-aware personalisation.
## Standard Event Types
| Type | Typical usage | Mandatory fields |
| ------------ | -------------------------------- | ------------------------------ |
| page\_view | Search results, PDP, checkout | page\_type |
| module\_view | Carousel / ad slot on a page | rank |
| impression | Single result shown to user | item\_id, rank |
| click | Tap, like, add-to-cart click | item\_id, click\_type |
| conversion | Order, booking, lead form submit | conversion\_type, item\_ids\[] |
| dwell\_time | Time user kept page open | dwell\_ms |
| scroll | How long they scrolled for | |
Sequen also supports custom event types that you can define with any set of properties to model your unique events.
## Reserved Fields
These keys have special meaning and must not be renamed or repurposed.
| Field | Type | Req | Notes |
| ----------------------- | -------------- | :---: | ----------------------------------------------------------------------------------------------- |
| id | string | | Unique per event. Autogenerated. |
| type | string | Yes | Standard event or custom event type. |
| original\_timestamp | datetime/unix | Yes | When the user performed the action. |
| server\_timestamp | datetime/unix | | When the recommendation was requested from Sequen on behalf of user. |
| ingest\_timestamp | datetime/unix | auto | When the event was received and ingested. |
| uid | string | Yes\* | Id of the user. (relation on User table) |
| sid (session\_id) | string | Yes\* | User session id. |
| cid (client\_id) | string | Yes\* | User Device, browser, etc. |
| rec\_id | string | | Used to end-to-end tracing of recommendations. |
| page\_view\_id | string | | ID of the page\_view event related to this event. Optional but recommended for event linking. |
| module\_view\_id | string | | ID of the module\_view event related to this event. Optional but recommended for event linking. |
| impression\_id | string | | Link a click back to its view. Optional but recommended for attribution. |
| rank | integer | | Ranking position of item. |
| item\_id / item\_ids\[] | string / array | | 1: N depending on event |
| item\_id\_relation | relation | | Defined what Table item\_id/item\_ids\[] belongs to. |
**At least one of `uid`, `sid`, or `cid` is required.** You must provide one or more of these identifiers to properly track user behavior across events.
While `page_view_id`, `module_view_id`, and `impression_id` are optional, including them significantly improves event attribution, funnel analysis, and model training. We recommend adding these fields when possible.
### Standard Event Type fields
| Field | Type | Required | Description |
| ---------------- | ------ | ------------------------- | --------------------------------------------------- |
| page\_type | string | Yes\* (page\_view event) | Name of page for view. (e.g., search, checkout) |
| click\_type | string | Yes\* (click event) | Type of click. (e.g., like, add\_to\_cart) |
| conversion\_type | string | Yes\* (conversion event) | Type of conversion. (e.g., purchase, add\_to\_cart) |
| dwell\_ms | number | Yes\* (dwell\_time event) | Dwell time. |
Anything not in the table above is treated as a custom field. Allowed field types: string, number, boolean, relation, `array`, time, embedding, object.
## Mandatory Fields By Event Type
| Event Type | Typical usage | Mandatory fields |
| ------------ | ---------------------------------------------- | ------------------------------ |
| page\_view | search result page, PDP, checkout | page\_type |
| module\_view | carousel, ad slot | rank |
| impression | individual record shown | item\_id, rank |
| click | any interaction (tap, like, add‑to‑cart click) | item\_id, click\_type |
| conversion | order, booking, lead submit | conversion\_type, item\_ids\[] |
| dwell\_time | time spent after load | dwell\_ms |
### Example impression
```json theme={null}
{
"id": "evt_c9f3c",
"type": "impression",
"original_timestamp": "2025-07-14T09:15:22.401Z",
"uid": "u_4432",
"page_view_id": "evt_c9f38",
"module_view_id": "evt_c9f39",
"item_id": "sku_99201",
"rank": 3,
"rec_id": "rec_0ujsswThIGTUYm2K8FjOOfXtY1K",
"traffic_source": "seo",
"seen_above_fold": true,
"device_info": {
"platform": "ios",
"version": "17.2",
"model": "iPhone 15"
}
}
```
### Example conversion
```json theme={null}
{
"id": "evt_d0a11",
"type": "conversion",
"original_timestamp": "2025-07-14T09:17:48.009Z",
"uid": "u_4432",
"conversion_type": "purchase",
"item_ids": ["sku_99201", "sku_88211"],
"order_total": 699.98,
"currency": "USD",
"payment_method": "apple_pay",
"shipping_address": {
"country": "US",
"state": "CA",
"postal_code": "94102"
}
}
```
### Example media event
```json theme={null}
{
"id": "evt_cb002",
"type": "video_pause",
"original_timestamp": "2025-07-14T09:18:21Z",
"uid": "u_4432",
"item_id": "video_128",
"current_time_sec": 212,
"reason": "user_click"
}
```
## Endpoint
```
POST /v1/events
```
## Example Request
```bash theme={null}
curl -X POST https://api.sequen.com/v1/events \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"type": "impression",
"original_timestamp": "2025-07-14T09:15:22.401Z",
"uid": "u_4432",
"page_view_id": "evt_c9f38",
"module_view_id": "evt_c9f39",
"item_id": "sku_99201",
"rank": 3
}'
```
```bash theme={null}
curl -X POST https://api.sequen.com/v1/events \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"events": [
{
"type": "impression",
"original_timestamp": "2025-07-14T09:15:22.401Z",
"uid": "u_4432",
"item_id": "sku_99201",
"rank": 3
},
{
"type": "click",
"original_timestamp": "2025-07-14T09:15:24.000Z",
"uid": "u_4432",
"impression_id": "evt_c9f3c",
"item_id": "sku_99201",
"click_type": "add_to_cart"
}
]
}'
```
## Good, Better, Best Data
Our data request is divided into three tiers: Good, Better, and Best. Below, we outline the data included in each category, with "Good" covering the mandatory requirements for a baseline model, while "Better" and "Best" provide additional data to enhance performance.
| Event Attribute | Good | Better | Best |
| -------------------- | :--: | :----: | :--: |
| page\_id | ✅ | ✅ | ✅ |
| search\_query | ✅ | ✅ | ✅ |
| geolocation | ✅ | ✅ | ✅ |
| locale/language | ✅ | ✅ | ✅ |
| device\_type | ✅ | ✅ | ✅ |
| logged\_in | ✅ | ✅ | ✅ |
| partial\_form\_fills | | ✅ | ✅ |
| review\_click | | ✅ | ✅ |
| outbound\_click | | ✅ | ✅ |
| dwell\_time | | ✅ | ✅ |
| referral\_source | | ✅ | ✅ |
| scroll\_depth | | | ✅ |
| cart\_content | | | ✅ |
| email\_campaign | | | ✅ |
| push\_notifications | | | ✅ |
## Why so much event detail?
Rich, well‑linked behavioral data lets us train and continuously improve ranking models, similar to how Algolia unlocks Dynamic Re‑Ranking and Personalization only when click & conversion events are sent.