List Interactions

Authorizations

Authorization

string

header

required

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

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. REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.

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

Query Parameters

limit

integer | null

offset

integer | null

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

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

filters.AND

FilterCondition · object[] | null

Logical AND operation - all conditions must be true

Represents a single filter condition.

Attributes: field: The field to filter on operator: The comparison operator value: The value to compare against

Show child attributes

filters.AND.field

string

required

Field name to filter on

filters.AND.value

required

Value to compare against

Show child attributes

filters.AND.value.field

string

required

The dot-notation path to the value in the runtime query request, e.g., 'inputs.user_id'

filters.AND.value.type

string

default:dynamic

Allowed value: "dynamic"

filters.AND.operator

enum<string>

default:eq

Comparison operator

Available options:

eq,

ne,

gt,

lt,

gte,

lte,

in,

nin,

contains,

starts_with,

ends_with,

regex,

exists,

is_null,

text

Example:

[
  {
    "field": "name",
    "operator": "eq",
    "value": "John"
  },
  {
    "field": "age",
    "operator": "gte",
    "value": 30
  }
]

filters.OR

FilterCondition · object[] | null

Logical OR operation - at least one condition must be true

Represents a single filter condition.

Attributes: field: The field to filter on operator: The comparison operator value: The value to compare against

Show child attributes

filters.OR.field

string

required

Field name to filter on

filters.OR.value

required

Value to compare against

Show child attributes

filters.OR.value.field

string

required

The dot-notation path to the value in the runtime query request, e.g., 'inputs.user_id'

filters.OR.value.type

string

default:dynamic

Allowed value: "dynamic"

filters.OR.operator

enum<string>

default:eq

Comparison operator

Available options:

eq,

ne,

gt,

lt,

gte,

lte,

in,

nin,

contains,

starts_with,

ends_with,

regex,

exists,

is_null,

text

Example:

[
  {
    "field": "status",
    "operator": "eq",
    "value": "active"
  },
  {
    "field": "role",
    "operator": "eq",
    "value": "admin"
  }
]

filters.NOT

FilterCondition · object[] | null

Logical NOT operation - all conditions must be false

Represents a single filter condition.

Attributes: field: The field to filter on operator: The comparison operator value: The value to compare against

Show child attributes

filters.NOT.field

string

required

Field name to filter on

filters.NOT.value

required

Value to compare against

Show child attributes

filters.NOT.value.field

string

required

The dot-notation path to the value in the runtime query request, e.g., 'inputs.user_id'

filters.NOT.value.type

string

default:dynamic

Allowed value: "dynamic"

filters.NOT.operator

enum<string>

default:eq

Comparison operator

Available options:

eq,

ne,

gt,

lt,

gte,

lte,

in,

nin,

contains,

starts_with,

ends_with,

regex,

exists,

is_null,

text

Example:

[
  {
    "field": "department",
    "operator": "eq",
    "value": "HR"
  },
  {
    "field": "location",
    "operator": "eq",
    "value": "remote"
  }
]

filters.case_sensitive

boolean | null

default:false

Whether to perform case-sensitive matching

Example:

true

Example:

{ "position": { "lte": 5 } }

sort

SortOption · object

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

sort.field

string

required

Field to sort by, supports dot notation for nested fields

Example:

"created_at"

sort.direction

enum<string>

default:asc

Sort direction

Available options:

asc,

desc

Example:

"desc"

Example:

{ "direction": "desc", "field": "timestamp" }

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

Show child attributes

results.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.

results.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 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

results.position

integer

required

Position in search results where interaction occurred (0-indexed). 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

results.interaction_id

string

required

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

results.metadata

Metadata · object

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

Example:

{
  "device": "mobile",
  "duration_ms": 5000,
  "page": "search_results",
  "viewport_position": 0.75
}

results.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.

Example:

"user_abc123"

results.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.

Example:

"sess_abc123"

results.execution_id

string | null

ID of the retriever execution that generated these results. NOT REQUIRED but HIGHLY RECOMMENDED for training and optimization. Links the interaction back to the exact search query, pipeline configuration, and stage execution that produced the results the user saw. Essential for: fine-tuning embeddings, training rerankers, query understanding, and tracing which pipeline configs produce better user engagement. Retrieve from the retriever execution response and pass to interactions.

Example:

"exec_abc123xyz"

results.retriever_id

string | null

ID of the retriever that was executed. NOT REQUIRED but RECOMMENDED for multi-retriever analytics. Enables comparing performance across different retriever configurations. If execution_id is provided, retriever_id can be inferred from the execution record.

Example:

"ret_abc123"

results.query_snapshot

Query Snapshot · object

Snapshot of the query input that generated these results. HIGHLY RECOMMENDED for training optimization. Storing the query directly enables 10-100x faster training data extraction by avoiding expensive joins to execution records. Use the same format as retriever query input (e.g., {'text': '...', 'filters': {...}}). Essential for: embedding fine-tuning (query-document pairs), query expansion learning, and analyzing which query patterns lead to better engagement. NOT REQUIRED but strongly recommended for production use cases involving model training.

Example:

{ "text": "wireless headphones" }

results.document_score

number | null

Initial retrieval score of this document when shown to the user. HIGHLY RECOMMENDED for Learning to Rank (LTR). This is a critical feature for reranker training - helps the model learn how to adjust initial scores based on user engagement. Should match the score from the retriever execution results. NOT REQUIRED but strongly recommended for LTR and reranker training.

Example:

0.95

results.result_set_size

integer | null

Total number of results shown to the user in this search. NOT REQUIRED but useful for context. Helps understand interaction patterns - clicking position 5 of 10 results is different from position 5 of 100 results. Useful for position bias correction and CTR analysis.

Required range: x >= 1

Example:

10

results.timestamp

string | null

ISO 8601 timestamp when the interaction was recorded. System-assigned. Used for time-based analysis, training data recency weighting, and temporal trends in user behavior.

Example:

"2025-01-15T10:30:00Z"

pagination

PaginationResponse · object

required

Pagination information for navigating result pages

Show child attributes

pagination.total

integer

required

pagination.page

integer

required

pagination.page_size

integer

required

pagination.total_pages

integer

required

pagination.next_page

string | null

pagination.previous_page

string | null

Health

Namespaces

Buckets

Feature Extractors

Collections

Retrievers

Taxonomies

Clusters

Analytics

Tasks

Webhooks

List Interactions

Authorizations

Headers

Query Parameters

Body

Response