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<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"
  }
}

Example media event

{
  "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

Single Event
Bulk Events

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.

Introduction

Data Management v2

Search & Recommendations

Chat

Embeddings

Why send rich event data?

Standard Event Types

Reserved Fields

Standard Event Type fields

Mandatory Fields By Event Type

Example impression

Example conversion

Example media event

Endpoint

Example Request

Good, Better, Best Data

Why so much event detail?

​Why send rich event data?

​Standard Event Types

​Reserved Fields

​Standard Event Type fields

​Mandatory Fields By Event Type

​Example impression

​Example conversion

​Example media event

​Endpoint

​Example Request

​Good, Better, Best Data

​Why so much event detail?

Why send rich event data?

Standard Event Types

Reserved Fields

Standard Event Type fields

Mandatory Fields By Event Type

Example impression

Example conversion

Example media event

Endpoint

Example Request

Good, Better, Best Data

Why so much event detail?