Sign in
Retriever Interactions

Create Interaction

Record a search interaction (view, click, feedback, etc.).

Automatically computes and injects metadata.reward_value based on the interaction types and the retriever's reward_map configuration. This pre-computed value is used by the learned-fusion bandit aggregation query so it doesn't need to join against the retriever config at read time.

Deduplication (Phase 4e): If (execution_id, feature_id, interaction_type) has already been recorded within the last 5 minutes the duplicate is silently dropped.

Session cache (Phase 1b): When session_id is present the interaction is also written to the Redis session cache so the Thompson Sampling bandit can incorporate it in real time (before ClickHouse write-then-read latency settles).

post/v1/retrievers/interactions

Request body

feature_idstring 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_typeInteractionType[] 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.

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

metadataobject 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_idstring 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_idstring 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_idstring 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_idstring 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_snapshotobject 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_scorenumber 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_sizeinteger 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_uristring 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_atstring 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.

Example request

{
  "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"
}

Response

Successful Response

feature_idstring 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_typeInteractionType[] 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.

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

metadataobject 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_idstring 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_idstring 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_idstring 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_idstring 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_snapshotobject 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_scorenumber 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_sizeinteger 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_uristring 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_atstring 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_idstring 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).

deduplicatedboolean

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.

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

warningstring 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).

Example response

{
  "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"
}

Changes

Changed in 2 of the 30 revisions of this API.56

  • 5307993e44d355See the full diff
    • ●

      added the new add_to_project enum value to the interaction_type/items/ response property for the response status 200

      response-property-enum-value-added

    • ●

      added the new download enum value to the interaction_type/items/ response property for the response status 200

      response-property-enum-value-added

    • ●

      added the new play enum value to the interaction_type/items/ response property for the response status 200

      response-property-enum-value-added

    • ●

      added the new rating enum value to the interaction_type/items/ response property for the response status 200

      response-property-enum-value-added

    • ●

      added the new save enum value to the interaction_type/items/ response property for the response status 200

      response-property-enum-value-added

    • ○

      added the new add_to_project enum value to the request property interaction_type/items/

      request-property-enum-value-added

    • ○

      added the new download enum value to the request property interaction_type/items/

      request-property-enum-value-added

    • ○

      added the new play enum value to the request property interaction_type/items/

      request-property-enum-value-added

    • ○

      added the new rating enum value to the request property interaction_type/items/

      request-property-enum-value-added

    • ○

      added the new save enum value to the request property interaction_type/items/

      request-property-enum-value-added

  • 5d4c905106b41See the full diff
    • ○

      the endpoint scheme security BearerAuth AND NamespaceHeader was added to the API

      api-security-added

    This revision also has 3 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog