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' \
  --data '
{
  "document_id": "<string>",
  "interaction_type": [],
  "position": 1,
  "execution_id": "exec_abc123xyz",
  "query_snapshot": {
    "text": "wireless headphones"
  },
  "document_score": 0.95,
  "result_set_size": 10,
  "session_id": "sess_abc123",
  "metadata": {}
}
'
import requests

url = "https://api.mixpeek.com/v1/public/retrievers/{public_name}/interactions"

payload = {
    "document_id": "<string>",
    "interaction_type": [],
    "position": 1,
    "execution_id": "exec_abc123xyz",
    "query_snapshot": { "text": "wireless headphones" },
    "document_score": 0.95,
    "result_set_size": 10,
    "session_id": "sess_abc123",
    "metadata": {}
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    document_id: '<string>',
    interaction_type: [],
    position: 1,
    execution_id: 'exec_abc123xyz',
    query_snapshot: {text: 'wireless headphones'},
    document_score: 0.95,
    result_set_size: 10,
    session_id: 'sess_abc123',
    metadata: {}
  })
};

fetch('https://api.mixpeek.com/v1/public/retrievers/{public_name}/interactions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.mixpeek.com/v1/public/retrievers/{public_name}/interactions",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'document_id' => '<string>',
    'interaction_type' => [
        
    ],
    'position' => 1,
    'execution_id' => 'exec_abc123xyz',
    'query_snapshot' => [
        'text' => 'wireless headphones'
    ],
    'document_score' => 0.95,
    'result_set_size' => 10,
    'session_id' => 'sess_abc123',
    'metadata' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.mixpeek.com/v1/public/retrievers/{public_name}/interactions"

	payload := strings.NewReader("{\n  \"document_id\": \"<string>\",\n  \"interaction_type\": [],\n  \"position\": 1,\n  \"execution_id\": \"exec_abc123xyz\",\n  \"query_snapshot\": {\n    \"text\": \"wireless headphones\"\n  },\n  \"document_score\": 0.95,\n  \"result_set_size\": 10,\n  \"session_id\": \"sess_abc123\",\n  \"metadata\": {}\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
HttpResponse<String> response = Unirest.post("https://api.mixpeek.com/v1/public/retrievers/{public_name}/interactions")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"document_id\": \"<string>\",\n  \"interaction_type\": [],\n  \"position\": 1,\n  \"execution_id\": \"exec_abc123xyz\",\n  \"query_snapshot\": {\n    \"text\": \"wireless headphones\"\n  },\n  \"document_score\": 0.95,\n  \"result_set_size\": 10,\n  \"session_id\": \"sess_abc123\",\n  \"metadata\": {}\n}")
  .asString();
require 'uri'
require 'net/http'

url = URI("https://api.mixpeek.com/v1/public/retrievers/{public_name}/interactions")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"document_id\": \"<string>\",\n  \"interaction_type\": [],\n  \"position\": 1,\n  \"execution_id\": \"exec_abc123xyz\",\n  \"query_snapshot\": {\n    \"text\": \"wireless headphones\"\n  },\n  \"document_score\": 0.95,\n  \"result_set_size\": 10,\n  \"session_id\": \"sess_abc123\",\n  \"metadata\": {}\n}"

response = http.request(request)
puts response.read_body
{
  "status": 123,
  "error": {
    "message": "<string>",
    "type": "<string>",
    "code": "<string>",
    "details": {}
  },
  "success": false
}
{
  "status": 123,
  "error": {
    "message": "<string>",
    "type": "<string>",
    "code": "<string>",
    "details": {}
  },
  "success": false
}
{
  "status": 123,
  "error": {
    "message": "<string>",
    "type": "<string>",
    "code": "<string>",
    "details": {}
  },
  "success": false
}
{
  "status": 123,
  "error": {
    "message": "<string>",
    "type": "<string>",
    "code": "<string>",
    "details": {}
  },
  "success": false
}
{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>"
    }
  ]
}
{
  "status": 123,
  "error": {
    "message": "<string>",
    "type": "<string>",
    "code": "<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 | null

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)

Examples:

"doc_abc123"

"prod_xyz789"

​
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: IMPRESSION: Result was rendered on screen (passive signal, no user action) VIEW: User viewed a search result CLICK: User clicked on a search result DWELL: User lingered on a result (weaker than long_view, stronger than view) 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:
impression,
view,
click,
dwell,
positive_feedback,
negative_feedback,
purchase,
add_to_cart,
wishlist,
long_view,
share,
bookmark,
query_refinement,
zero_results,
filter_toggle,
skip,
return_to_results
Examples:
["click"]

["view", "click"]

["positive_feedback"]
​
position
integer
required

Position in search results (0-indexed)

Required range: x >= 0
Examples:

0

1

5

15

​
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 | null

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 | null

Additional context about the interaction

Response

Successful Response