Analytics Events

Analytics events let you track user interactions with your search experience. By sending search, click, conversion, and custom events, you enable Seekora to power relevance tuning, query suggestions, A/B testing insights, and conversion analytics.

Authentication

Header	Description
x-storeid	Your store identifier
x-storesecret	Read-only API secret

Personalization Headers

Include these headers to attribute events to specific users and sessions. This data powers personalized search results and analytics attribution.

Header	Description
x-user-id	Logged-in user identifier
x-anon-id	Anonymous visitor identifier
x-session-id	Current browsing session identifier

Send a Single Event

POST /analytics/event

Search Event

Sent when a user performs a search query.

curl -X POST "https://api.seekora.ai/analytics/event" \
  -H "Content-Type: application/json" \
  -H "x-storeid: your-store-id" \
  -H "x-storesecret: your-read-secret" \
  -H "x-user-id: user_8294" \
  -H "x-session-id: sess_a1b2c3" \
  -d '{
    "event_type": "search",
    "data": {
      "query": "wireless headphones",
      "total_results": 47,
      "page": 0,
      "filters_applied": {
        "brand": ["AudioPro", "SoundMax"],
        "price_range": "50-200"
      }
    },
    "timestamp": "2025-09-15T14:32:00Z"
  }'

Click Event

Sent when a user clicks on a search result.

curl -X POST "https://api.seekora.ai/analytics/event" \
  -H "Content-Type: application/json" \
  -H "x-storeid: your-store-id" \
  -H "x-storesecret: your-read-secret" \
  -H "x-user-id: user_8294" \
  -H "x-session-id: sess_a1b2c3" \
  -d '{
    "event_type": "click",
    "data": {
      "query": "wireless headphones",
      "document_id": "prod_1001",
      "position": 3
    },
    "timestamp": "2025-09-15T14:32:15Z"
  }'

Conversion Event

Sent when a user completes a purchase or other goal action after clicking a search result.

curl -X POST "https://api.seekora.ai/analytics/event" \
  -H "Content-Type: application/json" \
  -H "x-storeid: your-store-id" \
  -H "x-storesecret: your-read-secret" \
  -H "x-user-id: user_8294" \
  -H "x-session-id: sess_a1b2c3" \
  -d '{
    "event_type": "conversion",
    "data": {
      "query": "wireless headphones",
      "document_id": "prod_1001",
      "revenue": 199.99,
      "currency": "USD",
      "order_id": "order_55821"
    },
    "timestamp": "2025-09-15T14:45:00Z"
  }'

Custom Event

Track any domain-specific interaction not covered by the built-in event types.

curl -X POST "https://api.seekora.ai/analytics/event" \
  -H "Content-Type: application/json" \
  -H "x-storeid: your-store-id" \
  -H "x-storesecret: your-read-secret" \
  -H "x-session-id: sess_a1b2c3" \
  -d '{
    "event_type": "custom",
    "data": {
      "name": "add_to_wishlist",
      "document_id": "prod_1001",
      "query": "wireless headphones",
      "metadata": {
        "list_name": "Holiday Gifts"
      }
    },
    "timestamp": "2025-09-15T14:33:00Z"
  }'

Single Event Response

{
  "status": "accepted",
  "event_id": "evt_9f8e7d6c5b4a"
}

Send Batch Events

Send up to 100 events in a single request for improved throughput.

POST /analytics/batch

curl -X POST "https://api.seekora.ai/analytics/batch" \
  -H "Content-Type: application/json" \
  -H "x-storeid: your-store-id" \
  -H "x-storesecret: your-read-secret" \
  -H "x-session-id: sess_a1b2c3" \
  -d '{
    "events": [
      {
        "event_type": "search",
        "data": { "query": "running shoes", "total_results": 83 },
        "timestamp": "2025-09-15T15:00:00Z"
      },
      {
        "event_type": "click",
        "data": { "query": "running shoes", "document_id": "prod_3010", "position": 1 },
        "timestamp": "2025-09-15T15:00:12Z"
      },
      {
        "event_type": "conversion",
        "data": { "query": "running shoes", "document_id": "prod_3010", "revenue": 129.00, "currency": "USD" },
        "timestamp": "2025-09-15T15:05:30Z"
      }
    ]
  }'

Batch Response

{
  "status": "accepted",
  "accepted": 3,
  "rejected": 0
}

Validate Events

Use the validation endpoint to test event payloads without persisting them. This is useful during development and integration testing.

POST /analytics/validate

curl -X POST "https://api.seekora.ai/analytics/validate" \
  -H "Content-Type: application/json" \
  -H "x-storeid: your-store-id" \
  -H "x-storesecret: your-read-secret" \
  -d '{
    "event_type": "click",
    "data": {
      "document_id": "prod_1001",
      "position": 3
    }
  }'

Validation Response (Success)

{
  "valid": true,
  "warnings": []
}

Validation Response (Failure)

{
  "valid": false,
  "errors": [
    "Field 'data.query' is recommended for click events to enable search attribution"
  ],
  "warnings": [
    "No timestamp provided; server time will be used"
  ]
}

Best Practices

• Include query in click and conversion events. This links the interaction back to the originating search and enables funnel analysis.
• Use the batch endpoint for high-traffic pages. Buffer events client-side and flush them periodically or on page unload to reduce the number of HTTP requests.
• Always provide a timestamp. If omitted, the server uses its own receive time, which may differ from the actual interaction time due to network latency or client-side buffering.
• Validate during development. Use the /analytics/validate endpoint to catch schema issues before they reach production.
• Send at least x-anon-id or x-session-id. Without any identity headers, events cannot be attributed to user journeys or sessions.