Track Interaction Batch

curl --request POST \
  --url https://api.mixpeek.com/v1/public/retrievers/{public_name}/interactions/batch \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Public-API-Key: <x-public-api-key>' \
  --data '
{
  "interactions": [
    {
      "document_id": "<string>",
      "interaction_type": [
        "view"
      ],
      "position": 1,
      "execution_id": "exec_abc123xyz",
      "query_snapshot": {
        "text": "wireless headphones"
      },
      "document_score": 0.95,
      "result_set_size": 10,
      "session_id": "sess_abc123",
      "metadata": {}
    }
  ]
}
'

{
  "status": 123,
  "error": {
    "message": "<string>",
    "type": "<string>",
    "details": {}
  },
  "success": false
}

Public API

Track Interaction Batch

Track multiple interactions in a single request (batching).

More efficient than sending individual interaction requests. Use this for batching viewport visibility, bulk actions, etc.

Authentication:

Requires X-Public-API-Key header
Password NOT required (tracking should work even without auth)

Recommended Headers:

X-Session-ID: Applied to all interactions in the batch

Limits:

Maximum 100 interactions per batch

Example:

curl -X POST "https://api.mixpeek.com/v1/public/retrievers/video-search/interactions/batch" \
  -H "X-Public-API-Key: prk_abc123..." \
  -H "X-Session-ID: sess_xyz..." \
  -H "Content-Type: application/json" \
  -d '{
    "interactions": [
      {
        "document_id": "doc_123",
        "interaction_type": ["VIEW"],
        "position": 0,
        "execution_id": "exec_abc"
      },
      {
        "document_id": "doc_456",
        "interaction_type": ["VIEW"],
        "position": 1,
        "execution_id": "exec_abc"
      }
    ]
  }'

POST

public

retrievers

{public_name}

interactions

batch

Track Interaction Batch

curl --request POST \
  --url https://api.mixpeek.com/v1/public/retrievers/{public_name}/interactions/batch \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Public-API-Key: <x-public-api-key>' \
  --data '
{
  "interactions": [
    {
      "document_id": "<string>",
      "interaction_type": [
        "view"
      ],
      "position": 1,
      "execution_id": "exec_abc123xyz",
      "query_snapshot": {
        "text": "wireless headphones"
      },
      "document_score": 0.95,
      "result_set_size": 10,
      "session_id": "sess_abc123",
      "metadata": {}
    }
  ]
}
'

{
  "status": 123,
  "error": {
    "message": "<string>",
    "type": "<string>",
    "details": {}
  },
  "success": false
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

X-Session-ID

string | null

X-Public-API-Key

string

required

Path Parameters

public_name

string

required

Public name of the published retriever

Body

application/json

Request to track multiple interactions in batch.

interactions

PublicInteractionRequest · object[]

required

List of interactions to track (max 100 per batch)

Required array length: 1 - 100 elements

Show child attributes

interactions.document_id

string

required

ID of the document that was interacted with (from search results)

interactions.interaction_type

enum<string>[]

required

Type(s) of interaction that occurred

Minimum array length: 1

Types of user interactions with search results.

These interaction types are used to track user behavior and improve retrieval quality through Learning to Rank (LTR), collaborative filtering, and embedding fine-tuning.

Values: VIEW: User viewed a search result CLICK: User clicked on a search result POSITIVE_FEEDBACK: User explicitly marked result as relevant/helpful NEGATIVE_FEEDBACK: User explicitly marked result as not relevant PURCHASE: User purchased the item (high-value conversion signal) ADD_TO_CART: User added item to cart (mid-funnel signal) WISHLIST: User saved item for later (engagement signal) LONG_VIEW: User spent significant time viewing (dwell time) SHARE: User shared the result (strong engagement signal) BOOKMARK: User bookmarked the result QUERY_REFINEMENT: User modified their search query ZERO_RESULTS: Query yielded no results (helps identify gaps) FILTER_TOGGLE: User modified filters (helps understand intent) SKIP: User skipped over result to click something lower (negative signal) RETURN_TO_RESULTS: User quickly returned to results (negative signal)

Usage in Retrieval Optimization: - LTR (Learning to Rank): Train models to predict click-through rates - Collaborative Filtering: Find similar users/items based on interactions - Embedding Fine-tuning: Adjust embeddings based on what users actually click - Query Understanding: Analyze refinements and zero-result queries - Result Quality: Identify poorly-performing results via skip/return patterns

Available options:

view,

click,

positive_feedback,

negative_feedback,

purchase,

add_to_cart,

wishlist,

long_view,

share,

bookmark,

query_refinement,

zero_results,

filter_toggle,

skip,

return_to_results

interactions.position

integer

required

Position in search results (0-indexed)

Required range: x >= 0

interactions.execution_id

string | null

ID of the retriever execution that generated these results. HIGHLY RECOMMENDED for analytics.

Example:

"exec_abc123xyz"

interactions.query_snapshot

Query Snapshot · object

Snapshot of the query that generated these results. HIGHLY RECOMMENDED for training optimization.

Example:

{ "text": "wireless headphones" }

interactions.document_score

number | null

Initial retrieval score of this document

Example:

0.95

interactions.result_set_size

integer | null

Total number of results shown

Required range: x >= 1

Example:

10

interactions.session_id

string | null

Session identifier for tracking user journey

Example:

"sess_abc123"

interactions.metadata

Metadata · object

Additional context about the interaction

Response

Successful Response

Track Interaction Get Public Retriever Template

⌘I

Health

Organizations

Namespaces

Buckets

Feature Extractors

Collections

Retrievers

Taxonomies

Clusters

Templates

Analytics

Resource Search

Inference

Agent Sessions

Tasks

Webhooks

Notifications

Triggers

Track Interaction Batch

Authorizations

Headers

Path Parameters

Body

Response