Events
Behavioral events track how users interact with search results — clicks, cart adds, purchases, and more. This data powers future ranking improvements and conversion analytics.
query_id field. Pass it with your events to
link user actions back to the search that produced them.Record a batch of behavioral events for analytics and future ranking models.
Request body
| Parameter | Type | Description |
|---|---|---|
| events required | object[] | Array of event objects to record (max 1000 per request). |
Event object
| Parameter | Type | Description |
|---|---|---|
| type required | string | Event type: click, add_to_cart, purchase, conversion, or view. |
| index_uid required | string | Index UID the document belongs to. |
| document_id required | string | Primary key of the document in the index. |
| query_id optional | string | Query ID from the search response that led to this event. |
| session_id optional | string | Client-generated session identifier for grouping events. |
| position optional | number | 0-indexed position of the document in search results. |
| timestamp optional | string | ISO 8601 timestamp. Server time used if omitted. |
| metadata optional | object | Arbitrary key-value data (e.g. revenue, quantity, currency). |
Example
curl -X POST https://search.example.com/v1/events \ -H "Authorization: Bearer sk_search_live_..." \ -H "Content-Type: application/json" \ -d '{ "events": [ { "type": "click", "index_uid": "products", "document_id": "prod_123", "query_id": "qry_a1b2c3d4e5f6g7h8", "session_id": "sess_xyz", "position": 3 }, { "type": "add_to_cart", "index_uid": "products", "document_id": "prod_123", "query_id": "qry_a1b2c3d4e5f6g7h8", "metadata": { "variant_id": "var_1", "quantity": 2 } } ] }'
SDK
await skirre.sendEvents({ events: [ { type: 'click', index_uid: 'products', document_id: 'prod_123', query_id: 'qry_a1b2c3d4e5f6g7h8', position: 3, }, { type: 'purchase', index_uid: 'products', document_id: 'prod_123', query_id: 'qry_a1b2c3d4e5f6g7h8', metadata: { revenue: 4999, currency: 'USD' }, }, ], });
Response 202 Accepted
{
"accepted": 2
}Response fields
| Parameter | Type | Description |
|---|---|---|
| accepted required | number | Number of events accepted for processing. |
Event types
Each event must have one of these types:
| Parameter | Type | Description |
|---|---|---|
| click optional | User clicked on a search result. | |
| view optional | User viewed a product detail page from search results. | |
| add_to_cart optional | User added a product to their cart. | |
| purchase optional | User purchased a product. Include revenue in metadata. | |
| conversion optional | Generic conversion event for custom goals. |
Linking to searches
Search responses include a query_id field. Pass this value in your events to
connect user behavior to the search query that initiated it. This link is essential for
computing click-through rates and training ranking models.
// 1. Search and capture query_id const results = await idx.search('running shoes'); const queryId = results.query_id; // 2. When a user clicks a result, send the event await skirre.sendEvents({ events: [{ type: 'click', index_uid: 'products', document_id: results.hits[0].id, query_id: queryId, position: 0, }], });
Batch limits
You can send up to 1,000 events per request. Events are validated
synchronously (type, required fields, index existence) and then written asynchronously.
The 202 Accepted status confirms the events passed validation and are queued
for storage.