> ## Documentation Index > Fetch the complete documentation index at: https://docs.mixpeek.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # List Interactions > List interactions with optional filters and pagination. Supports hybrid filtering: simple fields + advanced LogicalOperator. ## OpenAPI ````yaml post /v1/retrievers/interactions/list openapi: 3.1.0 info: title: Mixpeek API description: >- This is the Mixpeek API, providing access to various endpoints for data processing and retrieval. termsOfService: https://mixpeek.com/terms contact: name: Mixpeek Support url: https://mixpeek.com/contact email: info@mixpeek.com version: '0.82' servers: - url: https://api.mixpeek.com description: Production security: [] paths: /v1/retrievers/interactions/list: post: tags: - Retriever Interactions summary: List Interactions description: |- List interactions with optional filters and pagination. Supports hybrid filtering: simple fields + advanced LogicalOperator. operationId: list_interactions_v1_retrievers_interactions_list_post parameters: - name: limit in: query required: false schema: anyOf: - type: integer maximum: 1000 minimum: 1 - type: 'null' title: Limit - name: page_size in: query required: false schema: anyOf: - type: integer maximum: 1000 minimum: 1 - type: 'null' title: Page Size - name: offset in: query required: false schema: anyOf: - type: integer maximum: 10000 minimum: 0 - type: 'null' title: Offset - name: page in: query required: false schema: anyOf: - type: integer minimum: 1 - type: 'null' title: Page - name: cursor in: query required: false schema: anyOf: - type: string - type: 'null' title: Cursor - name: include_total in: query required: false schema: type: boolean default: false title: Include Total requestBody: content: application/json: schema: $ref: '#/components/schemas/ListInteractionsRequest' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/ListInteractionsResponse' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: schemas: ListInteractionsRequest: properties: execution_id: anyOf: - type: string - type: 'null' title: Execution Id description: >- Filter by retriever execution ID. Most common query: find all interactions from a specific search execution. Example: 'exec_abc123' examples: - exec_abc123 - exec_550e8400e29b retriever_id: anyOf: - type: string - type: 'null' title: Retriever Id description: >- Filter by retriever ID. Compare performance across different retriever configurations. Example: 'ret_product_search_v2' examples: - ret_product_search - ret_baseline_v1 session_id: anyOf: - type: string - type: 'null' title: Session Id description: >- Filter by session ID. Track user journey across multiple searches within a session. Example: 'sess_xyz789' examples: - sess_abc123 - sess_xyz789_1234567890 user_id: anyOf: - type: string - type: 'null' title: User Id description: >- Filter by user ID. Analyze behavior of specific users for personalization insights. Example: 'user_456' examples: - user_abc123 - customer_456 feature_id: anyOf: - type: string - type: 'null' title: Feature Id description: >- Filter by feature/document ID. Find all interactions with a specific document across all searches. Example: 'doc_abc123' examples: - doc_abc123 - prod_xyz789 interaction_type: anyOf: - type: string - type: 'null' title: Interaction Type description: >- Filter by interaction type. Use to find specific behaviors like clicks, purchases, or feedback. Example: 'click', 'positive_feedback' examples: - click - positive_feedback - purchase filters: anyOf: - $ref: '#/components/schemas/LogicalOperator-Input' - type: 'null' description: >- 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. examples: - position: lte: 5 - AND: - field: position operator: lte value: 5 - field: interaction_type operator: in value: - click - purchase - OR: - field: interaction_type operator: eq value: purchase - field: metadata.duration_ms operator: gte value: 10000 sort: anyOf: - $ref: '#/components/schemas/SortOption' - type: 'null' description: >- 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'} examples: - direction: desc field: timestamp - direction: asc field: position search: anyOf: - type: string - type: 'null' title: Search description: >- Full-text search across metadata fields. NOT REQUIRED. Use to search interaction metadata content. examples: - mobile device - campaign_summer_2024 type: object title: ListInteractionsRequest description: |- 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"}}} ListInteractionsResponse: properties: results: items: $ref: '#/components/schemas/InteractionResponse' type: array title: Results description: List of interactions matching the query filters pagination: $ref: '#/components/schemas/PaginationResponse' description: Pagination information for navigating result pages items: items: $ref: '#/components/schemas/InteractionResponse' type: array title: Items description: >- 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). readOnly: true type: object required: - results - pagination - items title: ListInteractionsResponse description: >- Response for listing interactions with pagination. Returns a paginated list of interaction records matching the query filters. ErrorResponse: properties: success: type: boolean title: Success description: Always false for error responses default: false status: type: integer title: Status description: HTTP status code for this error error: $ref: '#/components/schemas/ErrorDetail' description: Error details payload type: object required: - status - error title: ErrorResponse description: Error response model. examples: - error: details: id: ns_123 resource: namespace message: Namespace not found type: NotFoundError status: 404 success: false HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError LogicalOperator-Input: properties: AND: anyOf: - items: anyOf: - $ref: '#/components/schemas/LogicalOperator-Input' - $ref: '#/components/schemas/FilterCondition' type: array - type: 'null' title: And description: Logical AND operation - all conditions must be true example: - field: name operator: eq value: John - field: age operator: gte value: 30 OR: anyOf: - items: anyOf: - $ref: '#/components/schemas/LogicalOperator-Input' - $ref: '#/components/schemas/FilterCondition' type: array - type: 'null' title: Or description: Logical OR operation - at least one condition must be true example: - field: status operator: eq value: active - field: role operator: eq value: admin NOT: anyOf: - items: anyOf: - $ref: '#/components/schemas/LogicalOperator-Input' - $ref: '#/components/schemas/FilterCondition' type: array - type: 'null' title: Not description: Logical NOT operation - all conditions must be false example: - field: department operator: eq value: HR - field: location operator: eq value: remote case_sensitive: anyOf: - type: boolean - type: 'null' title: Case Sensitive description: Whether to perform case-sensitive matching default: false example: true additionalProperties: true type: object title: LogicalOperator description: >- 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"}). SortOption: properties: field: type: string title: Field description: Field to sort by, supports dot notation for nested fields example: created_at direction: $ref: '#/components/schemas/SortDirection' description: Sort direction default: asc example: desc type: object required: - field title: SortOption description: |- Specifies how to sort query results. Attributes: field: Field to sort by direction: Sort direction (ascending or descending) InteractionResponse: properties: feature_id: type: string title: Feature Id description: >- 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. examples: - doc_abc123 - prod_xyz789 - feat_12345 interaction_type: items: $ref: '#/components/schemas/InteractionType' type: array minItems: 1 title: Interaction Type description: >- 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. examples: - - click - - positive_feedback - click - long_view - - negative_feedback - - purchase - click position: type: integer minimum: 0 title: Position description: >- 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. examples: - 0 - 1 - 5 - 15 metadata: anyOf: - additionalProperties: true type: object - type: 'null' title: Metadata description: >- 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: anyOf: - type: string - type: 'null' title: User Id description: >- 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: anyOf: - type: string - type: 'null' title: Session Id description: >- 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. examples: - sess_abc123 - session_xyz789_1234567890 execution_id: anyOf: - type: string - type: 'null' title: Execution Id description: >- 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. examples: - exec_abc123xyz - exec_550e8400e29b41d4 retriever_id: anyOf: - type: string - type: 'null' title: Retriever Id description: >- 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. examples: - ret_abc123 - ret_product_search_v2 query_snapshot: anyOf: - additionalProperties: true type: object - type: 'null' title: Query Snapshot description: >- 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. examples: - text: wireless headphones - filters: price: lte: 1000 text: laptop - context: summer collection text: red shoes document_score: anyOf: - type: number - type: 'null' title: Document Score description: >- 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. examples: - 0.95 - 0.87 - 0.62 result_set_size: anyOf: - type: integer minimum: 1 - type: 'null' title: Result Set Size description: >- 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. examples: - 10 - 20 - 50 - 100 feature_uri: anyOf: - type: string - type: 'null' title: Feature Uri description: >- 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. examples: - mixpeek://text_extractor@v1/multilingual_e5_large_instruct_v1 - mixpeek://clip_extractor@v1/image_embedding occurred_at: anyOf: - type: string format: date-time - type: 'null' title: Occurred At description: >- 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. examples: - '2026-01-15T10:30:00Z' - '2025-12-01T00:00:00+00:00' interaction_id: anyOf: - type: string - type: 'null' title: Interaction Id description: >- 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). examples: - int_abc123xyz789 - 550e8400-e29b-41d4-a716-446655440000 deduplicated: type: boolean title: Deduplicated description: >- 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. default: false timestamp: anyOf: - type: string - type: 'null' title: Timestamp description: >- 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. examples: - '2025-01-15T10:30:00Z' - '2025-01-15T14:45:30.123Z' warning: anyOf: - type: string - type: 'null' title: Warning description: >- 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). type: object required: - feature_id - interaction_type - position title: InteractionResponse description: |- Response model for a stored interaction. Extends SearchInteraction with system-assigned fields. examples: - 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 - description: Simple click interaction with recommended fields for training document_score: 0.85 feature_id: doc_abc123 interaction_type: - click position: 2 query_snapshot: text: machine learning tutorials - description: Engaged view with metadata and execution tracking document_score: 0.92 execution_id: exec_abc123xyz feature_id: prod_xyz789 interaction_type: - view - click - long_view metadata: device: mobile duration_ms: 12000 viewport_position: 0.85 position: 0 query_snapshot: filters: price: lte: 100 text: wireless headphones result_set_size: 20 retriever_id: ret_product_search session_id: sess_abc user_id: user_123 - description: Negative feedback document_score: 0.78 feature_id: doc_bad456 interaction_type: - negative_feedback - return_to_results metadata: interaction_reason: not_relevant position: 5 query_snapshot: text: python tutorial result_set_size: 50 session_id: sess_xyz - description: >- Purchase conversion with full tracking (high-value signal for training) document_score: 0.88 execution_id: exec_purchase_789 feature_id: prod_789 interaction_type: - purchase metadata: conversion_time_seconds: 120 purchase_amount: 199.99 position: 1 query_snapshot: text: noise cancelling headphones result_set_size: 50 retriever_id: ret_product_search session_id: sess_purchase_001 user_id: user_456 PaginationResponse: properties: total: anyOf: - type: integer - type: 'null' title: Total page: anyOf: - type: integer - type: 'null' title: Page page_size: anyOf: - type: integer - type: 'null' title: Page Size total_pages: anyOf: - type: integer - type: 'null' title: Total Pages next_page: anyOf: - type: string - type: 'null' title: Next Page previous_page: anyOf: - type: string - type: 'null' title: Previous Page next_cursor: anyOf: - type: string - type: 'null' title: Next Cursor type: object title: PaginationResponse description: |- PaginationResponse. Cursor-based pagination response: - Use next_cursor for navigation - Total count fields only populated when include_total=true ErrorDetail: properties: message: type: string title: Message description: Human-readable error message type: type: string title: Type description: Stable error type identifier (machine-readable) code: anyOf: - type: string - type: 'null' title: Code description: >- Fine-grained error code for programmatic handling (e.g., namespace_name_taken, feature_extractor_not_found). Present only when consumers may need to branch on a specific error condition. details: anyOf: - additionalProperties: true type: object - type: 'null' title: Details description: >- Optional structured details to help debugging (validation errors, IDs, etc.) type: object required: - message - type title: ErrorDetail description: Error detail model. ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type type: object required: - loc - msg - type title: ValidationError FilterCondition: properties: field: type: string title: Field description: Field name to filter on operator: $ref: '#/components/schemas/FilterOperator' description: Comparison operator default: eq value: anyOf: - $ref: '#/components/schemas/DynamicValue' - {} title: Value description: Value to compare against type: object required: - field - value title: FilterCondition description: |- Represents a single filter condition. Attributes: field: The field to filter on operator: The comparison operator value: The value to compare against SortDirection: type: string enum: - asc - desc title: SortDirection description: Sort direction options. InteractionType: type: string enum: - impression - view - click - dwell - positive_feedback - negative_feedback - purchase - add_to_cart - wishlist - long_view - share - bookmark - query_refinement - zero_results - filter_toggle - skip - return_to_results title: InteractionType description: >- 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: IMPRESSION: Result was rendered on screen (passive signal, no user action) VIEW: User viewed a search result CLICK: User clicked on a search result DWELL: User lingered on a result (weaker than long_view, stronger than view) 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 FilterOperator: type: string enum: - eq - ne - gt - lt - gte - lte - in - nin - contains - starts_with - ends_with - regex - exists - is_null - text - phrase title: FilterOperator description: Supported filter operators across database implementations. DynamicValue: properties: type: type: string const: dynamic title: Type default: dynamic field: type: string title: Field description: >- The dot-notation path to the value in the runtime query request, e.g., 'inputs.user_id' examples: - inputs.query_text - filters.AND[0].value type: object required: - field title: DynamicValue description: A value that should be dynamically resolved from the query request. ````