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 | |
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. |
array<string>, 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
{
"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
{
"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"
}
}
{
"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
Example Request
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
}'
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. 
