Skip to main content
GET
/
v1
/
retrievers
/
interactions
/
{interaction_id}
Get Interaction
curl --request GET \
  --url https://api.mixpeek.com/v1/retrievers/interactions/{interaction_id} \
  --header 'Authorization: Bearer <token>' \
  --header 'X-Namespace: <x-namespace>'
{
  "description": "Simple click interaction",
  "feature_id": "doc_abc123",
  "interaction_type": [
    "click"
  ],
  "position": 2
}

Authorizations

​
Authorization
string
header
required

Bearer token authentication using your API key. Format: 'Bearer your_api_key'. To get an API key, create an account at mixpeek.com/start and generate a key in your account settings.

Headers

​
Authorization
string
required

REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.

Examples:

"Bearer sk_live_abc123def456"

"Bearer sk_test_xyz789"

​
X-Namespace
string
required

REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'

Examples:

"ns_abc123def456"

"production"

"my-namespace"

Path Parameters

​
interaction_id
string
required

Response

Successful Response

Response model for a stored interaction.

Extends SearchInteraction with system-assigned fields.

​
feature_id
string
required

ID of the document/feature that was interacted with. REQUIRED. This should be the document_id returned in retriever results. Used to track which specific items users engage with.

Examples:

"doc_abc123"

"prod_xyz789"

"feat_12345"

​
interaction_type
enum<string>[]
required

List of interaction types that occurred. REQUIRED. Multiple types can be recorded simultaneously (e.g., VIEW + CLICK + LONG_VIEW for a result the user engaged with). Use the InteractionType enum values.

Minimum length: 1
Examples:
["click"]
["positive_feedback", "click", "long_view"]
["negative_feedback"]
["purchase", "click"]
​
interaction_id
string
required

Unique identifier for this interaction record. System-assigned UUID. Use this to reference the interaction in subsequent requests.

Examples:

"int_abc123xyz789"

"550e8400-e29b-41d4-a716-446655440000"

​
position
integer | null

Position in search results where interaction occurred (0-indexed). NOT REQUIRED. Critical for Learning to Rank - helps identify position bias. E.g., position=0 means first result, position=9 means 10th result. Higher engagement at lower positions suggests higher quality.

Required range: x >= 0
Examples:

0

1

5

15

​
metadata
object | null

Additional context about the interaction. NOT REQUIRED. Can include device, duration, viewport info, etc. Use this to enrich interaction data with application-specific context.

Examples:
{
  "device": "mobile",
  "duration_ms": 5000,
  "page": "search_results",
  "viewport_position": 0.75
}
{
  "interaction_reason": "not_relevant",
  "page_number": 2,
  "results_count": 50,
  "search_latency_ms": 150
}
​
user_id
string | null

Customer's authenticated user identifier. NOT REQUIRED. Persists across sessions for long-term tracking. Enables personalization and user-specific metrics. Use your application's user ID format.

Examples:

"user_abc123"

"customer_456"

"usr_xyz789"

​
session_id
string | null

Temporary identifier for a single search session. NOT REQUIRED. Typically 30min-1hr duration. Tracks anonymous and authenticated users within a session. Use to group related queries and understand search journeys.

Examples:

"sess_abc123"

"session_xyz789_1234567890"