List Interactions

List interactions with optional filters and pagination.

Supports hybrid filtering: simple fields + advanced LogicalOperator.

POST /v1/retrievers/interactions/list

List Interactions

cURL

curl --request POST \
  --url https://api.mixpeek.com/v1/retrievers/interactions/list \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Namespace: <api-key>' \
  --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"
}
'

200

{
  "results": [
    {
      "description": "Minimal click interaction (query_snapshot and document_score optional)",
      "execution_id": "exec_minimal_123",
      "feature_id": "doc_abc123",
      "interaction_type": [
        "click"
      ],
      "position": 2,
      "session_id": "sess_minimal"
    }
  ],
  "pagination": {
    "total": 123,
    "page": 123,
    "page_size": 123,
    "total_pages": 123,
    "next_page": "<string>",
    "previous_page": "<string>",
    "next_cursor": "<string>"
  },
  "items": [
    {
      "description": "Minimal click interaction (query_snapshot and document_score optional)",
      "execution_id": "exec_minimal_123",
      "feature_id": "doc_abc123",
      "interaction_type": [
        "click"
      ],
      "position": 2,
      "session_id": "sess_minimal"
    }
  ]
}

Authorizations

Authorization · string · header · required

Mixpeek API key, sent as Authorization: Bearer mxp_sk_.... Create one in Studio under Settings → API Keys, or with an admin key via POST /v1/organizations/users/{user_email}/api-keys. A missing, malformed, unknown, revoked, inactive or expired key returns 401; a key without the permission, scope or plan an operation needs returns 403.

X-Namespace · string · header · required

Namespace id (ns_...), not the namespace name. This scopes the request rather than authenticating it, and it is required on every operation marked x-mixpeek-namespace-scoped.

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

next_cursor · string | null

after · string | null

include_total · boolean · default: false

Body

application/json

Keys this body does not declare are refused with 422 extra_forbidden naming the accepted keys (since 2026-11-02).

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.

Show child attributes

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'}

Show child attributes

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

200

application/json

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

Show child attributes

pagination · PaginationResponse · object · required

Pagination information for navigating result pages

Show child attributes

items · InteractionResponse · object[] · required · deprecated · read-only

Deprecated alias of results, kept for existing clients. Read results, the row key every list route shares.

Show child attributes