Skip to main content
POST
/
v1
/
retrievers
/
interactions
/
list
List Interactions
curl --request POST \
  --url https://api.mixpeek.com/v1/retrievers/interactions/list \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Namespace: <x-namespace>' \
  --data '{
  "execution_id": "exec_abc123",
  "retriever_id": "ret_product_search",
  "session_id": "sess_abc123",
  "user_id": "user_abc123",
  "feature_id": "doc_abc123",
  "interaction_type": "click",
  "filters": {
    "position": {
      "lte": 5
    }
  },
  "sort": {
    "direction": "desc",
    "field": "timestamp"
  },
  "search": "mobile device"
}'
{
  "results": [
    {
      "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"
    }
  ],
  "pagination": {
    "total": 123,
    "page": 123,
    "page_size": 123,
    "total_pages": 123,
    "next_page": "<string>",
    "previous_page": "<string>"
  }
}

Authorizations

​
Authorization
string
header
required

Bearer token authentication using your API key. Format: 'Bearer your_api_key'. To get an API key, create an account at mixpeek.com/start and generate a key in your account settings.

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.

Examples:

"Bearer sk_live_abc123def456"

"Bearer sk_test_xyz789"

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

Examples:

"ns_abc123def456"

"production"

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

Examples:

"exec_abc123"

"exec_550e8400e29b"

​
retriever_id
string | null

Filter by retriever ID. Compare performance across different retriever configurations. Example: 'ret_product_search_v2'

Examples:

"ret_product_search"

"ret_baseline_v1"

​
session_id
string | null

Filter by session ID. Track user journey across multiple searches within a session. Example: 'sess_xyz789'

Examples:

"sess_abc123"

"sess_xyz789_1234567890"

​
user_id
string | null

Filter by user ID. Analyze behavior of specific users for personalization insights. Example: 'user_456'

Examples:

"user_abc123"

"customer_456"

​
feature_id
string | null

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
string | null

Filter by interaction type. Use to find specific behaviors like clicks, purchases, or feedback. Example: 'click', 'positive_feedback'

Examples:

"click"

"positive_feedback"

"purchase"

​
filters
object | null

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. 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"}).

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
object | null

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'} Specifies how to sort query results.

Attributes: field: Field to sort by direction: Sort direction (ascending or descending)

Examples:
{ "direction": "desc", "field": "timestamp" }
{ "direction": "asc", "field": "position" }
​
search
string | null

Full-text search across metadata fields. NOT REQUIRED. Use to search interaction metadata content.

Examples:

"mobile device"

"campaign_summer_2024"

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

​
pagination
object
required

Pagination information for navigating result pages