Interaction tracking allows you to record how users engage with search results, enabling personalized ranking, relevance improvement, and usage analytics.

​
Overview

In Mixpeek, interactions represent how users engage with search results. By tracking these interactions, you can gather valuable data to improve search relevance, personalize results, and gain insights into user behavior and content performance.

User Engagement Data

Record how users interact with search results, including clicks, views, and conversions

Relevance Signals

Use interaction data as signals to improve search relevance and personalization

​
Types of Interactions

Mixpeek supports several types of user interactions that you can track:

​
Recording Interactions

There is no dedicated public Interactions API in the OpenAPI spec. Track interactions in your application (e.g., analytics or your backend), then use those signals with supported endpoints like Retriever Execute.

​
Apply interaction signals at query time

Use exclusion or boosting via filters/sorts when calling Execute Retriever: 
curl -X POST https://api.mixpeek.com/v1/retrievers/RET_ID/execute \
  -H "Authorization: Bearer $API_KEY" \
  -H "X-Namespace: ns_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": {"query_text": "wireless headphones"},
    "filters": {
      "AND": [
        {"field": "document_id", "operator": "nin", "value": ["doc_already_clicked_1", "doc_already_clicked_2"]}
      ]
    },
    "limit": 20
  }'
FieldTypeDescription
typestringInteraction type such as click, view, conversion
document_idstringDocument the user interacted with
user_idstringThe end-user identifier (pseudonymous recommended)
Interactions can be used to personalize and improve search results: Use interaction history to pre-filter or post-process results on the client or your server. When using the API directly, prefer supported features like filters and sorts.

​
User-based filtering example

curl -X POST https://api.mixpeek.com/v1/retrievers/RET_ID/execute \
  -H "Authorization: Bearer $API_KEY" \
  -H "X-Namespace: ns_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": {"query_text": "running shoes"},
    "filters": {
      "AND": [
        {"field": "document_id", "operator": "nin", "value": ["doc_clicked_1", "doc_clicked_2"]}
      ]
    },
    "limit": 20
  }'

​
Tracking Interactions Client-Side

For web applications, capture interactions in your app and send them to your backend or analytics system. Use those signals to inform subsequent Mixpeek queries. 
// Add click event listeners to search results
document.querySelectorAll('.search-result').forEach((element, index) => {
  element.addEventListener('click', async () => {
    const documentId = element.getAttribute('data-document-id');
    const payload = {
      type: 'click',
      document_id: documentId,
      position: index + 1,
      user_id: getCurrentUserId(),
      session_id: getSessionId(),
      metadata: {
        query: getCurrentQueryText(),
        device: getDeviceType(),
        page: 'search_results'
      }
    };

    // Send to your backend or analytics
    await fetch('/api/track-interaction', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(payload)
    });
  });
});

​
Analytics and Reporting

Use your existing analytics stack (e.g., Segment, Snowflake, BigQuery, ClickHouse) to store and analyze interaction events. Mixpeek does not expose analytics endpoints in the OpenAPI spec.

​
Best Practices

1

Track Consistently

Implement interaction tracking consistently across your application to collect comprehensive data.
2

Include Context

Capture relevant contextual information in the metadata field to make interactions more valuable for analysis.
3

Balance Privacy

Respect user privacy by anonymizing user identifiers where appropriate and complying with relevant regulations.
4

Optimize Volume

For high-traffic applications, consider batching interaction records or sampling to manage data volume.
Interaction data can grow rapidly in high-traffic applications. Consider implementing data retention policies and monitoring storage usage.

​
Implementation Strategies

Basic Implementation

  • Track clicks on search results
  • Use document position data
  • Include user and session IDs
  • Store basic query information

Intermediate Implementation

  • Track clicks, views, and conversions
  • Measure view duration and engagement depth
  • Include device and page context
  • Implement client-side tracking with JS SDK

Advanced Implementation

  • Track custom interaction types
  • Implement personalized ranking based on history
  • Use interaction data for A/B testing
  • Analyze interaction patterns for recommendations

Enterprise Implementation

  • Integrate with data warehouses
  • Implement comprehensive reporting
  • Use interaction data for model training
  • Create personalized content recommendations

​
API Reference

Relevant endpoints and guides: