---
title: "List Interactions"
method: POST
path: "/v1/retrievers/interactions/list"
tags: ["Retriever Interactions"]
---

# List Interactions

`POST /v1/retrievers/interactions/list`

List interactions with optional filters and pagination.

Supports hybrid filtering: simple fields + advanced LogicalOperator.

## Query parameters

- `limit` integer, nullable
- `page_size` integer, nullable
- `offset` integer, nullable
- `page` integer, nullable
- `cursor` string, nullable
- `next_cursor` string, nullable
- `after` string, nullable
- `include_total` boolean

## Request body

- ListInteractionsRequest — 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, nullable — Filter by retriever execution ID. Most common query: find all interactions from a specific search execution. Example: 'exec_abc123'
  - `retriever_id` string, nullable — Filter by retriever ID. Compare performance across different retriever configurations. Example: 'ret_product_search_v2'
  - `session_id` string, nullable — Filter by session ID. Track user journey across multiple searches within a session. Example: 'sess_xyz789'
  - `user_id` string, nullable — Filter by user ID. Analyze behavior of specific users for personalization insights. Example: 'user_456'
  - `feature_id` string, nullable — Filter by feature/document ID. Find all interactions with a specific document across all searches. Example: 'doc_abc123'
  - `interaction_type` string, nullable — Filter by interaction type. Use to find specific behaviors like clicks, purchases, or feedback. Example: 'click', 'positive_feedback'
  - `filters` LogicalOperatorInput — Represents a logical operation (AND, OR, NOT) on filter conditions. Allows nesting with a defined depth limit. Also supports shorthand syntax where field names can be passed directly as key-value pairs for equality filtering (e.g., {"metadata.title": "value"}).
    - `AND` union[], nullable — Logical AND operation - all conditions must be true
      - union
        - LogicalOperatorInput — recursive
        - FilterCondition — Represents a single filter condition. Attributes: field: The field to filter on operator: The comparison operator value: The value to compare against
          - `field` string, required — Field name to filter on
          - `operator` 'eq' | 'ne' | 'gt' | 'lt' | 'gte' | 'lte' | 'in' | 'nin' | 'contains' | 'starts_with' | 'ends_with' | 'regex' | 'exists' | 'is_null' | 'text' | 'phrase' | 'geo_radius' | 'geo_bounding_box' | 'geo_polygon' — Supported filter operators across database implementations.
          - `value` union, required — Value to compare against
            - DynamicValue — A value that should be dynamically resolved from the query request.
              - …
            - unknown
    - `OR` union[], nullable — Logical OR operation - at least one condition must be true
      - union
        - LogicalOperatorInput — recursive
        - FilterCondition — Represents a single filter condition. Attributes: field: The field to filter on operator: The comparison operator value: The value to compare against
          - `field` string, required — Field name to filter on
          - `operator` 'eq' | 'ne' | 'gt' | 'lt' | 'gte' | 'lte' | 'in' | 'nin' | 'contains' | 'starts_with' | 'ends_with' | 'regex' | 'exists' | 'is_null' | 'text' | 'phrase' | 'geo_radius' | 'geo_bounding_box' | 'geo_polygon' — Supported filter operators across database implementations.
          - `value` union, required — Value to compare against
            - DynamicValue — A value that should be dynamically resolved from the query request.
              - …
            - unknown
    - `NOT` union[], nullable — Logical NOT operation - all conditions must be false
      - union
        - LogicalOperatorInput — recursive
        - FilterCondition — Represents a single filter condition. Attributes: field: The field to filter on operator: The comparison operator value: The value to compare against
          - `field` string, required — Field name to filter on
          - `operator` 'eq' | 'ne' | 'gt' | 'lt' | 'gte' | 'lte' | 'in' | 'nin' | 'contains' | 'starts_with' | 'ends_with' | 'regex' | 'exists' | 'is_null' | 'text' | 'phrase' | 'geo_radius' | 'geo_bounding_box' | 'geo_polygon' — Supported filter operators across database implementations.
          - `value` union, required — Value to compare against
            - DynamicValue — A value that should be dynamically resolved from the query request.
              - …
            - unknown
    - `case_sensitive` boolean, nullable — Whether to perform case-sensitive matching
  - `sort` SortOption — Specifies how to sort query results. Attributes: field: Field to sort by direction: Sort direction (ascending or descending)
    - `field` string, required — Field to sort by, supports dot notation for nested fields
    - `direction` 'asc' | 'desc' — Sort direction options.
  - `search` string, nullable — Full-text search across metadata fields. NOT REQUIRED. Use to search interaction metadata content.

## Response `200`

Successful Response

- ListInteractionsResponse — Response for listing interactions with pagination. Returns a paginated list of interaction records matching the query filters.
  - `results` InteractionResponse[], required — List of interactions matching the query filters
    - `feature_id` string, required — ID of the document/feature that was interacted with. REQUIRED. This is the SAME value as the `document_id` returned in retriever execute results — you can pass it as either `feature_id` or `document_id` (the latter is accepted as an alias). Used to track which specific items users engage with.
    - `interaction_type` InteractionType[], 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.
    - `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.
    - `metadata` object, nullable — Additional context about the interaction. NOT REQUIRED. Can include device, duration, viewport info, etc. Use this to enrich interaction data with application-specific context.
    - `user_id` string, nullable — 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.
    - `session_id` string, nullable — 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. Also used by learned fusion (auto-tune) for within-session real-time adaptation: interactions sharing a session_id allow the bandit to update feature weights mid-session without waiting for batch aggregation.
    - `execution_id` string, nullable — 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.
    - `retriever_id` string, nullable — 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.
    - `query_snapshot` object, nullable — 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.
    - `document_score` number, nullable — 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.
    - `result_set_size` integer, nullable — 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.
    - `feature_uri` string, nullable — Feature URI that produced the clicked result (e.g. 'mixpeek://text_extractor@v1/embedding'). Required for learned fusion — interactions without this field do not contribute to weight learning.
    - `occurred_at` string, date-time, nullable — When the interaction actually happened (ISO 8601). OPTIONAL. Omit for live interactions — the server stamps 'now'. Supply this ONLY to backfill historical interactions (e.g. migrating existing click logs) so learned-fusion temporal decay weights them by their TRUE age. A naive datetime is interpreted as UTC; a future value is clamped to now. Backfilled events bypass the real-time session cache.
    - `interaction_id` string, nullable — Unique identifier for this interaction record. System-assigned UUID. Use this to reference the interaction in subsequent requests. Null when the interaction was deduplicated (see ``deduplicated`` field).
    - `deduplicated` boolean — True when this interaction was a duplicate of a recently recorded interaction with the same (execution_id, feature_id, interaction_type) tuple and was silently dropped. The ``interaction_id`` will be null.
    - `timestamp` string, nullable — 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.
    - `warning` string, nullable — Non-blocking warning about the interaction. Present when the request was accepted but may not behave as intended (e.g. missing feature_uri for learned fusion).
  - `pagination` PaginationResponse, required — PaginationResponse. Cursor-based pagination response: - Use next_cursor for navigation - Total count fields only populated when include_total=true
    - `total` integer, nullable
    - `page` integer, nullable
    - `page_size` integer, nullable
    - `total_pages` integer, nullable
    - `next_page` string, nullable
    - `previous_page` string, nullable
    - `next_cursor` string, nullable
  - `items` InteractionResponse[], required — 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).
    - `feature_id` string, required — ID of the document/feature that was interacted with. REQUIRED. This is the SAME value as the `document_id` returned in retriever execute results — you can pass it as either `feature_id` or `document_id` (the latter is accepted as an alias). Used to track which specific items users engage with.
    - `interaction_type` InteractionType[], 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.
    - `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.
    - `metadata` object, nullable — Additional context about the interaction. NOT REQUIRED. Can include device, duration, viewport info, etc. Use this to enrich interaction data with application-specific context.
    - `user_id` string, nullable — 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.
    - `session_id` string, nullable — 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. Also used by learned fusion (auto-tune) for within-session real-time adaptation: interactions sharing a session_id allow the bandit to update feature weights mid-session without waiting for batch aggregation.
    - `execution_id` string, nullable — 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.
    - `retriever_id` string, nullable — 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.
    - `query_snapshot` object, nullable — 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.
    - `document_score` number, nullable — 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.
    - `result_set_size` integer, nullable — 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.
    - `feature_uri` string, nullable — Feature URI that produced the clicked result (e.g. 'mixpeek://text_extractor@v1/embedding'). Required for learned fusion — interactions without this field do not contribute to weight learning.
    - `occurred_at` string, date-time, nullable — When the interaction actually happened (ISO 8601). OPTIONAL. Omit for live interactions — the server stamps 'now'. Supply this ONLY to backfill historical interactions (e.g. migrating existing click logs) so learned-fusion temporal decay weights them by their TRUE age. A naive datetime is interpreted as UTC; a future value is clamped to now. Backfilled events bypass the real-time session cache.
    - `interaction_id` string, nullable — Unique identifier for this interaction record. System-assigned UUID. Use this to reference the interaction in subsequent requests. Null when the interaction was deduplicated (see ``deduplicated`` field).
    - `deduplicated` boolean — True when this interaction was a duplicate of a recently recorded interaction with the same (execution_id, feature_id, interaction_type) tuple and was silently dropped. The ``interaction_id`` will be null.
    - `timestamp` string, nullable — 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.
    - `warning` string, nullable — Non-blocking warning about the interaction. Present when the request was accepted but may not behave as intended (e.g. missing feature_uri for learned fusion).

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not Found
- `422` — Validation Error
- `500` — Internal Server Error

---

[API](https://skmtc.net/mixpeek/apis/mixpeek-api.md) · [All operations](https://skmtc.net/mixpeek/apis/mixpeek-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/mixpeek/mixpeek-api/revisions/220a3b263fda/schema)