Skip to main content
POST
/
v1
/
public
/
retrievers
/
{public_name}
/
interactions
Track Interaction
curl --request POST \
  --url https://api.mixpeek.com/v1/public/retrievers/{public_name}/interactions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Public-API-Key: <x-public-api-key>' \
  --data '
{
  "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 a single interaction from public retriever.

Simplified wrapper around SearchInteraction for public API use.

​
document_id
string
required

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

​
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
​
position
integer
required

Position in search results (0-indexed)

Required range: x >= 0
​
execution_id
string | null

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

Example:

"exec_abc123xyz"

​
query_snapshot
Query Snapshot · object

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

Example:
{ "text": "wireless headphones" }
​
document_score
number | null

Initial retrieval score of this document

Example:

0.95

​
result_set_size
integer | null

Total number of results shown

Required range: x >= 1
Example:

10

​
session_id
string | null

Session identifier for tracking user journey

Example:

"sess_abc123"

​
metadata
Metadata · object

Additional context about the interaction

Response

Successful Response