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.

Tip
Every search response includes a query_id field. Pass it with your events to link user actions back to the search that produced them.
POST /v1/events Any key

Record a batch of behavioral events for analytics and future ranking models.

Request body

ParameterTypeDescription
events requiredobject[]Array of event objects to record (max 1000 per request).

Event object

ParameterTypeDescription
type requiredstringEvent type: click, add_to_cart, purchase, conversion, or view.
index_uid requiredstringIndex UID the document belongs to.
document_id requiredstringPrimary key of the document in the index.
query_id optionalstringQuery ID from the search response that led to this event.
session_id optionalstringClient-generated session identifier for grouping events.
position optionalnumber0-indexed position of the document in search results.
timestamp optionalstringISO 8601 timestamp. Server time used if omitted.
metadata optionalobjectArbitrary key-value data (e.g. revenue, quantity, currency).

Example

text
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

text
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

text
{
  "accepted": 2
}

Response fields

ParameterTypeDescription
accepted requirednumberNumber of events accepted for processing.

Event types

Each event must have one of these types:

ParameterTypeDescription
click optionalUser clicked on a search result.
view optionalUser viewed a product detail page from search results.
add_to_cart optionalUser added a product to their cart.
purchase optionalUser purchased a product. Include revenue in metadata.
conversion optionalGeneric 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.

text
// 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.

Note
Events are automatically purged after 90 days. For long-term analytics, export data via the Analytics endpoints.
Document scoring
Events feed into Skirre's automatic document scoring. When scoring is enabled, behavioral events are aggregated into popularity scores that boost popular items in search results.