> ## 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. # Track Interaction Batch > Track multiple interactions in a single request (batching). More efficient than sending individual interaction requests. Use this for batching viewport visibility, bulk actions, etc. **Authentication:** - API key is OPTIONAL (same as execute endpoint) - Password NOT required (tracking should work even without auth) **Recommended Headers:** - `X-Session-ID`: Applied to all interactions in the batch **Limits:** - Maximum 100 interactions per batch **Example:** ```bash curl -X POST "https://api.mixpeek.com/v1/public/retrievers/video-search/interactions/batch" \ -H "X-Session-ID: sess_xyz..." \ -H "Content-Type: application/json" \ -d '{ "interactions": [ { "document_id": "doc_123", "interaction_type": ["VIEW"], "position": 0, "execution_id": "exec_abc" }, { "document_id": "doc_456", "interaction_type": ["VIEW"], "position": 1, "execution_id": "exec_abc" } ] }' ``` ## OpenAPI ````yaml post /v1/public/retrievers/{public_name}/interactions/batch 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/public/retrievers/{public_name}/interactions/batch: post: tags: - Public Retriever API summary: Track Interaction Batch description: >- Track multiple interactions in a single request (batching). More efficient than sending individual interaction requests. Use this for batching viewport visibility, bulk actions, etc. **Authentication:** - API key is OPTIONAL (same as execute endpoint) - Password NOT required (tracking should work even without auth) **Recommended Headers:** - `X-Session-ID`: Applied to all interactions in the batch **Limits:** - Maximum 100 interactions per batch **Example:** ```bash curl -X POST "https://api.mixpeek.com/v1/public/retrievers/video-search/interactions/batch" \ -H "X-Session-ID: sess_xyz..." \ -H "Content-Type: application/json" \ -d '{ "interactions": [ { "document_id": "doc_123", "interaction_type": ["VIEW"], "position": 0, "execution_id": "exec_abc" }, { "document_id": "doc_456", "interaction_type": ["VIEW"], "position": 1, "execution_id": "exec_abc" } ] }' ``` operationId: >- track_interaction_batch_v1_public_retrievers__public_name__interactions_batch_post parameters: - name: public_name in: path required: true schema: type: string description: Public name of the published retriever title: Public Name description: Public name of the published retriever - name: X-Session-ID in: header required: false schema: anyOf: - type: string - type: 'null' title: X-Session-Id - name: X-Public-API-Key in: header required: false schema: anyOf: - type: string - type: 'null' title: X-Public-Api-Key requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PublicInteractionBatchRequest' responses: '200': description: Successful Response content: application/json: schema: {} '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: PublicInteractionBatchRequest: properties: interactions: items: $ref: '#/components/schemas/PublicInteractionRequest' type: array maxItems: 100 minItems: 1 title: Interactions description: List of interactions to track (max 100 per batch) type: object required: - interactions title: PublicInteractionBatchRequest description: Request to track multiple interactions in batch. 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 PublicInteractionRequest: properties: document_id: type: string title: Document Id description: ID of the document that was interacted with (from search results) examples: - doc_abc123 - prod_xyz789 interaction_type: items: $ref: '#/components/schemas/InteractionType' type: array minItems: 1 title: Interaction Type description: Type(s) of interaction that occurred examples: - - click - - view - click - - positive_feedback position: type: integer minimum: 0 title: Position description: Position in search results (0-indexed) examples: - 0 - 1 - 5 - 15 execution_id: anyOf: - type: string - type: 'null' title: Execution Id description: >- ID of the retriever execution that generated these results. HIGHLY RECOMMENDED for analytics. examples: - exec_abc123xyz query_snapshot: anyOf: - additionalProperties: true type: object - type: 'null' title: Query Snapshot description: >- Snapshot of the query that generated these results. HIGHLY RECOMMENDED for training optimization. examples: - text: wireless headphones - filters: price: lte: 1000 text: laptop document_score: anyOf: - type: number - type: 'null' title: Document Score description: Initial retrieval score of this document 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 examples: - 10 - 20 - 50 session_id: anyOf: - type: string - type: 'null' title: Session Id description: Session identifier for tracking user journey examples: - sess_abc123 metadata: anyOf: - additionalProperties: true type: object - type: 'null' title: Metadata description: Additional context about the interaction type: object required: - document_id - interaction_type - position title: PublicInteractionRequest description: |- Request to track a single interaction from public retriever. Simplified wrapper around SearchInteraction for public API use. 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 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 ````