Execute Retriever (Auto-Optimized)
Execute a retriever and return matching documents. The pipeline is automatically optimized before execution for best performance.
Automatic Optimization: Your pipeline stages are automatically transformed for optimal performance:
- Filters pushed down to reduce expensive operations
- Redundant stages merged or eliminated
- Grouping operations pushed to database layer (10-100x faster)
- Operations reordered for efficiency
Streaming Support: Set stream=true in the request body to receive real-time stage updates via SSE:
- Response uses text/event-stream content type
- Each stage emits stage_start and stage_complete events
- Final event contains complete results and pagination
- Useful for progress tracking and debugging
Response Includes (when stream=false):
- documents: Final matching documents
- pagination: Pagination metadata
- stage_statistics: Per-stage execution metrics
- budget: Credit/time consumption
- optimization_applied: Whether optimizations were applied
- optimization_summary: Details about transformations (when applied)
Optimization Summary Example:
{
"optimization_applied": true,
"optimization_summary": {
"original_stage_count": 5,
"optimized_stage_count": 3,
"optimization_time_ms": 8.2,
"rules_applied": ["push_down_filters", "group_by_push_down"],
"stage_reduction_pct": 40.0
}
}
Use the /explain endpoint to see the optimized execution plan before running.
Headers
REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.
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'
Path Parameters
Retriever ID or name. Pipeline will be automatically optimized before execution.
Body
Execution request with inputs, filters, and pagination parameters.
Runtime inputs for the retriever mapped to the input schema. Keys must match the retriever's input_schema field names. Values depend on field types (text, vector, filters, etc.). REQUIRED unless all retriever inputs have defaults.
Stages read these inputs to determine their behavior:
- Search stages: Read 'query', 'embedding', 'top_k'
- Filter stages: Read filter criteria from inputs
- Sort stages: Read sort preferences from inputs
- All stages: Can use template expressions like '{{INPUT.query}}' or '{{inputs.query}}' Template namespaces support both uppercase (INPUT, DOC, CONTEXT, STAGE) and lowercase (inputs, doc, context, stage) formats. All formats work identically.
Common input keys:
- 'query': Text search query
- 'embedding': Pre-computed vector for search
- 'top_k': Number of results to return
- 'min_score': Minimum relevance threshold
- Any custom fields defined in input_schema
Example: {"query": "machine learning", "top_k": 50, "min_score": 0.7}
OPTIONAL. List of collection identifiers to search. Can contain collection IDs, collection names, or both mixed together. When provided, OVERRIDES the retriever's default collections. When NOT provided, uses the retriever's default collections.
Identifier Resolution:
- IDs (start with 'col_'): Used directly
- Names: Automatically resolved to IDs before execution
- Mixed: Both IDs and names can be provided together
- Deduplication: Duplicate IDs are automatically removed
Use cases:
- Search specific collections: ["col_123", "marketing_2024"]
- Mix IDs and names: ["col_archived", "current_blog_posts"]
- Override retriever defaults: Specify different collections per query
Note: All identifiers must exist in the namespace or request will fail.
1["col_marketing_2024", "sales_materials"]Pagination strategy configuration. Defaults to cursor-based pagination with limit=20. Supported methods: OFFSET, CURSOR, SCROLL, KEYSET. Each method has different tradeoffs for performance and use cases.
- OffsetPaginationParams
- CursorPaginationParams
- ScrollPaginationParams
- KeysetPaginationParams
Response
Execution results with documents, pagination, statistics, and optimization details. Check optimization_summary to see how your pipeline was transformed for performance.
Response from retriever execution.
REQUIRED. Unique identifier for this execution run. Use this ID to track execution status, retrieve execution details, or query execution history. Format: 'exec_' prefix followed by alphanumeric token.
REQUIRED. Execution status indicating current state. Common values: 'completed', 'failed', 'processing', 'pending'. Check this field to determine if execution succeeded or requires retry.
REQUIRED. Final document results after retriever completion. Contains documents that passed through all retriever stages. Each document may include: document_id, payload (full document data), score (relevance score), metadata (collection-specific fields), and any fields added by enrichment/join stages. Empty array indicates no documents matched the query criteria. Note: Legacy format may use 'final_results' instead of 'documents'.
REQUIRED. Pagination metadata structure. Format varies by pagination method: Offset pagination: {total, limit, offset, has_next, has_previous}, Cursor pagination: {cursor, has_next, page_size}, Keyset pagination: {next_cursor, has_next}. Use this to navigate through result pages.
REQUIRED. Per-stage execution statistics including timing, document counts, cache hit rates, and stage-specific metrics. Use this to understand retriever performance and identify bottlenecks.
REQUIRED. Budget usage snapshot for this execution. Contains: credits_used (credits consumed), credits_remaining (remaining budget), time_used_ms (execution time), and budget limits. Use this to track resource consumption and enforce budget limits.
OPTIONAL. Retriever-level error message if execution failed. Only present when status='failed'. Contains human-readable error description to help diagnose the failure. Check stage_statistics for stage-specific errors.
"Retriever execution failed: Collection not found"
OPTIONAL. Whether automatic pipeline optimizations were applied before execution. Mixpeek automatically optimizes retrieval pipelines for performance by reordering stages, merging operations, and pushing work to the database layer. Optimizations preserve logical equivalence - you get the same results, just faster. When true, see optimization_summary for details about what changed.
OPTIONAL. Summary of pipeline optimizations applied before execution. Only present when optimization_applied=true. Contains: - original_stage_count: Number of stages in your original pipeline - optimized_stage_count: Number of stages after optimization - optimization_time_ms: Time spent optimizing (typically <100ms) - rules_applied: List of optimization rules that fired - stage_reduction_pct: Percentage reduction in stage count Use this to understand how the optimizer improved your pipeline. See OptimizationRuleType enum for detailed rule descriptions.
{
"optimization_time_ms": 8.2,
"optimized_stage_count": 3,
"original_stage_count": 5,
"rules_applied": ["push_down_filters", "group_by_push_down"],
"stage_reduction_pct": 40
}