Skip to main content
POST
/
v1
/
retrievers
/
interactions
/
list
List Interactions
curl --request POST \
  --url https://api.mixpeek.com/v1/retrievers/interactions/list \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "execution_id": "exec_abc123",
  "retriever_id": "ret_product_search",
  "session_id": "sess_abc123",
  "user_id": "user_abc123",
  "feature_id": "doc_abc123",
  "interaction_type": "click",
  "filters": {
    "position": {
      "lte": 5
    }
  },
  "sort": {
    "direction": "desc",
    "field": "timestamp"
  },
  "search": "mobile device"
}
'
{
  "results": [
    {
      "feature_id": "<string>",
      "interaction_type": [],
      "position": 1,
      "metadata": {
        "device": "mobile",
        "duration_ms": 5000,
        "page": "search_results",
        "viewport_position": 0.75
      },
      "user_id": "user_abc123",
      "session_id": "sess_abc123",
      "execution_id": "exec_abc123xyz",
      "retriever_id": "ret_abc123",
      "query_snapshot": {
        "text": "wireless headphones"
      },
      "document_score": 0.95,
      "result_set_size": 10,
      "feature_uri": "mixpeek://text_extractor@v1/multilingual_e5_large_instruct_v1",
      "occurred_at": "2026-01-15T10:30:00Z",
      "interaction_id": "int_abc123xyz789",
      "deduplicated": false,
      "timestamp": "2025-01-15T10:30:00Z",
      "warning": "<string>"
    }
  ],
  "pagination": {
    "total": 123,
    "page": 123,
    "page_size": 123,
    "total_pages": 123,
    "next_page": "<string>",
    "previous_page": "<string>",
    "next_cursor": "<string>"
  },
  "items": [
    {
      "feature_id": "<string>",
      "interaction_type": [],
      "position": 1,
      "metadata": {
        "device": "mobile",
        "duration_ms": 5000,
        "page": "search_results",
        "viewport_position": 0.75
      },
      "user_id": "user_abc123",
      "session_id": "sess_abc123",
      "execution_id": "exec_abc123xyz",
      "retriever_id": "ret_abc123",
      "query_snapshot": {
        "text": "wireless headphones"
      },
      "document_score": 0.95,
      "result_set_size": 10,
      "feature_uri": "mixpeek://text_extractor@v1/multilingual_e5_large_instruct_v1",
      "occurred_at": "2026-01-15T10:30:00Z",
      "interaction_id": "int_abc123xyz789",
      "deduplicated": false,
      "timestamp": "2025-01-15T10:30:00Z",
      "warning": "<string>"
    }
  ]
}

Authorizations

​
Authorization
string
header
required

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

Query Parameters

​
limit
integer | null
Required range: 1 <= x <= 1000
​
page_size
integer | null
Required range: 1 <= x <= 1000
​
offset
integer | null
Required range: 0 <= x <= 10000
​
page
integer | null
Required range: x >= 1
​
cursor
string | null
​
include_total
boolean
default:false

Body

application/json

Request for listing interactions with filters.

Supports both simple field filters (for common queries) and advanced LogicalOperator filters (for complex analytics). This hybrid approach follows the same pattern as the Tasks module.

Common Queries (Simple Fields): - Filter by execution: {"execution_id": "exec_abc"} - Filter by session: {"session_id": "sess_xyz"} - Filter by user: {"user_id": "user_123"}

Advanced Queries (LogicalOperator): - Range queries: {"filters": {"position": {"lte": 5}}} - Complex logic: {"filters": {"AND": [...]}} - Time ranges: {"filters": {"created_at": {"gte": "2025-01-01"}}}

​
execution_id
string | null

Filter by retriever execution ID. Most common query: find all interactions from a specific search execution. Example: 'exec_abc123'

Example:

"exec_abc123"

​
retriever_id
string | null

Filter by retriever ID. Compare performance across different retriever configurations. Example: 'ret_product_search_v2'

Example:

"ret_product_search"

​
session_id
string | null

Filter by session ID. Track user journey across multiple searches within a session. Example: 'sess_xyz789'

Example:

"sess_abc123"

​
user_id
string | null

Filter by user ID. Analyze behavior of specific users for personalization insights. Example: 'user_456'

Example:

"user_abc123"

​
feature_id
string | null

Filter by feature/document ID. Find all interactions with a specific document across all searches. Example: 'doc_abc123'

Example:

"doc_abc123"

​
interaction_type
string | null

Filter by interaction type. Use to find specific behaviors like clicks, purchases, or feedback. Example: 'click', 'positive_feedback'

Example:

"click"

​
filters
LogicalOperator · object | null

Advanced filters using LogicalOperator for complex analytics queries. Supports shorthand syntax and complex AND/OR/NOT logic. Use this for: range queries, complex conditions, metadata filtering. Examples: - Position range: {'position': {'lte': 5}} - Time range: {'timestamp': {'gte': '2025-01-01'}} - Complex: {'AND': [{'field': 'position', 'operator': 'lte', 'value': 5}, {'field': 'interaction_type', 'operator': 'in', 'value': ['click', 'purchase']}]} See LogicalOperator documentation for full syntax.

Example:
{ "position": { "lte": 5 } }
​
sort
SortOption · object | null

Sort options for ordering results. Default: timestamp descending (newest first). Examples: - Sort by timestamp: {'field': 'timestamp', 'direction': 'desc'} - Sort by position: {'field': 'position', 'direction': 'asc'}

Example:
{ "direction": "desc", "field": "timestamp" }
​
search
string | null

Full-text search across metadata fields. NOT REQUIRED. Use to search interaction metadata content.

Example:

"mobile device"

Response

Successful Response

Response for listing interactions with pagination.

Returns a paginated list of interaction records matching the query filters.

​
results
InteractionResponse · object[]
required

List of interactions matching the query filters

​
pagination
PaginationResponse · object
required

Pagination information for navigating result pages

​
items
InteractionResponse · object[]
required
read-only

Alias for results, always populated identically.

Other list endpoints and the SDK conventionally read items, so a caller doing resp["items"] (or .get("items")) previously got an empty/missing list here and silently saw "no interactions". Exposing both keys removes that footgun (FRUSTRATIONS 2026-06-25 | API/DX).