> ## 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. # 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, pagination and consistency_mode - 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 - limits: Every cap that clamped the request (setting, value asked for, value used, the cap's maximum, the stage), absent when nothing was capped. A capped run can return fewer documents than asked for. - optimization_applied: Whether optimizations were applied - optimization_summary: Details about transformations (when applied) **Optimization Summary Example:** ```json { "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. ## OpenAPI ````yaml post /v1/retrievers/{retriever_id}/execute 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: - BearerAuth: [] paths: /v1/retrievers/{retriever_id}/execute: post: tags: - Retrievers summary: Execute Retriever (Auto-Optimized) description: >- 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, pagination and consistency_mode - 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 - limits: Every cap that clamped the request (setting, value asked for, value used, the cap's maximum, the stage), absent when nothing was capped. A capped run can return fewer documents than asked for. - optimization_applied: Whether optimizations were applied - optimization_summary: Details about transformations (when applied) **Optimization Summary Example:** ```json { "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. operationId: execute_retriever_v1_retrievers__retriever_id__execute_post parameters: - name: retriever_id in: path required: true schema: type: string description: >- Retriever ID or name. Pipeline will be automatically optimized before execution. title: Retriever Id description: >- Retriever ID or name. Pipeline will be automatically optimized before execution. - name: return_presigned_urls in: query required: false schema: type: boolean description: >- Generate presigned URLs for S3-backed blobs and url-shaped fields. Also accepted as a body field — if either source is true, presigning is enabled. default: false title: Return Presigned Urls description: >- Generate presigned URLs for S3-backed blobs and url-shaped fields. Also accepted as a body field — if either source is true, presigning is enabled. - name: return_vectors in: query required: false schema: type: boolean description: >- Include vector embeddings in result documents. Also accepted as a body field — if either source is true, vectors are returned. default: false title: Return Vectors description: >- Include vector embeddings in result documents. Also accepted as a body field — if either source is true, vectors are returned. - name: explain in: query required: false schema: type: boolean description: >- Return the inline `explain_plan` (per-stage timings + optimization summary) in the response. Also accepted as a body field — if either source is true, the plan is included. default: false title: Explain description: >- Return the inline `explain_plan` (per-stage timings + optimization summary) in the response. Also accepted as a body field — if either source is true, the plan is included. - name: include_legacy_results in: query required: false schema: type: boolean description: >- DEPRECATED. Restore the legacy `results` alias (a byte-for-byte copy of `documents`). Off by default — `results` previously duplicated the entire document array in every response (~half the payload). Prefer `documents`; use this only as a temporary migration shim. default: false title: Include Legacy Results description: >- DEPRECATED. Restore the legacy `results` alias (a byte-for-byte copy of `documents`). Off by default — `results` previously duplicated the entire document array in every response (~half the payload). Prefer `documents`; use this only as a temporary migration shim. - name: skip_cache in: query required: false schema: type: boolean description: >- Bypass the execute/stage cache read for this request (a fresh execution; the result is still written to cache). Also accepted as a body field — if either source is true, the cache is skipped. default: false title: Skip Cache description: >- Bypass the execute/stage cache read for this request (a fresh execution; the result is still written to cache). Also accepted as a body field — if either source is true, the cache is skipped. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ExecuteRetrieverRequest' description: >- Execution request with inputs, filters, pagination, and optional stream parameter. Set stream=true to receive real-time stage updates via Server-Sent Events. description: >- Keys this body does not declare are refused with 422 extra_forbidden naming the accepted keys (since 2026-11-02). x-unknown-keys: until: '2026-11-02' then: 422 extra_forbidden responses: '200': description: >- Execution results with documents, pagination, statistics, and optimization details. When stream=true, returns Server-Sent Events. When stream=false, returns JSON response. content: application/json: schema: $ref: '#/components/schemas/ExecuteRetrieverResponse' '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: Unprocessable Entity content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: Too Many Requests content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '503': description: Service Unavailable content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - BearerAuth: [] NamespaceHeader: [] components: schemas: ExecuteRetrieverRequest: properties: inputs: additionalProperties: true type: object title: Inputs description: >- 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. 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 **Template Syntax** (Jinja2): Namespaces (uppercase or lowercase): - `INPUT` / `input`: Query inputs (e.g., `{{INPUT.query}}`) - `DOC` / `doc`: Document fields (e.g., `{{DOC.payload.title}}`) - `CONTEXT` / `context`: Execution context - `STAGE` / `stage`: Stage configuration - `SECRET` / `secret`: Vault secrets (e.g., `{{SECRET.api_key}}`) Accessing Data: - Dot notation: `{{DOC.payload.metadata.title}}` - Bracket notation: `{{DOC.payload['special-key']}}` - Array index: `{{DOC.items[0]}}`, `{{DOC.tags[2]}}` - Array first/last: `{{DOC.items | first}}`, `{{DOC.items | last}}` Array Operations: - Iterate: `{% for item in DOC.tags %}{{item}}{% endfor %}` - Extract key: `{{DOC.items | map(attribute='name') | list}}` - Join: `{{DOC.tags | join(', ')}}` - Length: `{{DOC.items | length}}` - Slice: `{{DOC.items[:5]}}` Conditionals: - If: `{% if DOC.status == 'active' %}...{% endif %}` - If-else: `{% if DOC.score > 0.8 %}high{% else %}low{% endif %}` - Ternary: `{{'yes' if DOC.enabled else 'no'}}` Built-in Functions: `max`, `min`, `abs`, `round`, `ceil`, `floor`, `utc_now`, `time_ago` Time Functions: `{{utc_now()}}` returns current UTC as ISO-8601, `{{time_ago(minutes=5)}}` returns UTC minus duration Custom Filters: `slugify` (URL-safe), `bool` (truthy coercion), `tojson` (JSON encode), `regex_search(pattern, group=0, ignore_case=false)` (first match, or '') S3 URLs: Internal S3 URLs (s3://bucket/key) are automatically presigned when accessed via DOC namespace. examples: - query: artificial intelligence top_k: 25 - min_score: 0.7 query: customer feedback top_k: 50 - category: blog embedding: - 0.1 - 0.2 - 0.3 top_k: 10 filters: anyOf: - additionalProperties: true type: object - type: 'null' title: Filters description: >- Optional ad-hoc filters applied at execution time. Merged (AND) with any filters already defined in the retriever's stages. Uses the standard LogicalOperator format: {"AND": [{"field": "brand", "operator": "eq", "value": "Acme"}]}. Supports operators: eq, ne, in, nin, gt, gte, lt, lte, contains, exists, is_null. examples: - AND: - field: brand operator: eq value: Acme - AND: - field: status operator: in value: - active - pending - field: score operator: gte value: 0.5 pagination: oneOf: - $ref: '#/components/schemas/OffsetPaginationParams' - $ref: '#/components/schemas/CursorPaginationParams' - $ref: '#/components/schemas/ScrollPaginationParams' - $ref: '#/components/schemas/KeysetPaginationParams' title: Pagination description: > Pagination strategy configuration. When omitted entirely, defaults to cursor-based pagination sized to the pipeline's declared final_top_k (author intent); pipelines that declare no final_top_k default to limit=10. Any explicit pagination (or the deprecated body 'limit') is honored exactly. IMPORTANT: Pagination params do NOT support template variables ({{INPUT.x}} or {{DOCUMENT.x}}). Pagination is a request-level parameter for slicing results, separate from pipeline business logic. Pass cursor/limit values directly from your client code. Cursor values come from the previous response's pagination.cursor field. Supported Methods: - CURSOR (default): Best for infinite scroll, stateless, opaque token - KEYSET: Most efficient, requires stable sort, stateless - OFFSET: Traditional page numbers, can have drift issues - SCROLL: Server-side state, best for bulk exports Use CURSOR for: - Infinite scroll UIs (mobile apps, feeds, timelines) - Real-time updates where consistency matters - When you can't jump to arbitrary pages Use KEYSET for: - Maximum performance with large result sets - Stable sort fields (e.g., score DESC, id ASC) - When you need truly stateless pagination Use OFFSET for: - Traditional page UIs with page numbers - When users need to jump to specific pages - Smaller result sets where drift is acceptable Use SCROLL for: - Bulk exports or processing large datasets - When you need to iterate through all results - Background jobs with progress tracking Example (cursor - first page): {"method": "cursor", "limit": 20, "cursor": null} Example (cursor - next page, using cursor from previous response): {"method": "cursor", "limit": 20, "cursor": "eyJvZmZzZXQiOjIwfQ=="} Example (offset): {"method": "offset", "page_size": 25, "page_number": 2} Example (keyset): {"method": "keyset", "limit": 20, "after": {"score": 0.73, "id": "doc_20"}} discriminator: propertyName: method mapping: cursor: '#/components/schemas/CursorPaginationParams' keyset: '#/components/schemas/KeysetPaginationParams' offset: '#/components/schemas/OffsetPaginationParams' scroll: '#/components/schemas/ScrollPaginationParams' limit: anyOf: - type: integer maximum: 500 minimum: 1 - type: 'null' title: Limit description: >- Shorthand for the pagination page size: the most documents this response returns. A top-level 'page_size' is accepted as the same value. Prefer 'pagination' (for example {"method": "cursor", "limit": 100}). When 'pagination' is absent, this value sizes the default cursor pagination of the final result set, and the response's pagination cursor fetches the next page. When both are sent and disagree, 'pagination' wins and a top-level response warning names the conflict. Sending 'limit' and 'page_size' with different values is refused. deprecated: true examples: - null - 25 stream: type: boolean title: Stream description: >- Enable streaming execution to receive real-time stage updates via Server-Sent Events (SSE). NOT REQUIRED - defaults to False for standard execution. When stream=True: - Response uses text/event-stream content type - Each stage completion emits a StreamStageEvent - Events include: stage_start, stage_complete, stage_error, execution_complete - Clients receive intermediate results and statistics as stages execute - Useful for progress tracking, debugging, and partial result display When stream=False (default): - Response returns after all stages complete - Returns a single RetrieverExecutionResponse with final results - Lower overhead for simple queries Use streaming when: - You want to show real-time progress to users - You need to display intermediate results - Pipeline has many stages or long-running operations - Debugging or monitoring pipeline performance Example streaming client (JavaScript): ```javascript const eventSource = new EventSource('/v1/retrievers/ret_123/execute?stream=true'); eventSource.onmessage = (event) => { const stageEvent = JSON.parse(event.data); if (stageEvent.event_type === 'stage_complete') { console.log(`Stage ${stageEvent.stage_name} completed`); console.log(`Documents: ${stageEvent.documents.length}`); } }; ``` Example streaming client (Python): ```python import requests response = requests.post('/v1/retrievers/ret_123/execute', json={'inputs': {...}, 'stream': True}, stream=True) for line in response.iter_lines(): if line.startswith(b'data: '): event = json.loads(line[6:]) print(f"Stage {event['stage_name']}: {event['event_type']}") ``` default: false examples: - false - true expand: anyOf: - items: type: string type: array - type: 'null' title: Expand description: >- OPTIONAL. List of fields containing document IDs to resolve inline. Referenced documents are fetched and attached under an '_expanded' key in each result document. Supports dot-notation for nested fields (e.g., 'items.product_id'). Max 50 unique references per request. Depth is limited to 1 (no recursive expansion). examples: - - customer_id - - customer_id - items.product_id skip_cache: type: boolean title: Skip Cache description: >- OPTIONAL. Bypass stage result cache for this execution. When True, all stages execute fresh without cache lookup. Useful after corpus updates, retriever config changes, or engine deploys. Results are still written to cache for future requests. default: false examples: - false - true return_presigned_urls: type: boolean title: Return Presigned Urls description: >- Generate presigned URLs for S3-backed blobs and url-shaped fields in result documents. Also accepted as a `return_presigned_urls` query parameter; if either source is true, presigning is enabled. default: false examples: - false - true return_vectors: type: boolean title: Return Vectors description: >- Include vector embeddings in result documents. Also accepted as a `return_vectors` query parameter; if either source is true, vectors are returned. default: false examples: - false - true write_token: anyOf: - type: string - type: 'null' title: Write Token description: >- OPTIONAL. Pass the `write_token` returned by a prior direct upsert (options.write_token=true) to get read-your-writes consistency: the read is routed to the primary shard, where your just-written document is immediately searchable, instead of an eventually-consistent replica that can lag several seconds behind. Omit for normal (eventual) reads. consistency: anyOf: - $ref: '#/components/schemas/ReadConsistencyOption' - type: 'null' description: >- OPTIONAL. The read consistency for this execution. Omit to use the deployment default. A write_token always reads strong. target_collection_id: anyOf: - type: string - type: 'null' title: Target Collection Id description: >- OPTIONAL. A collection in this namespace to write this execution's results into. Each result document is written there as a document of its own: the result's fields as its payload, the source document's stored vectors (so the collection is searchable on the same features), and the execution in its lineage under _internal.lineage (the source document and collection, the execution id, the retriever id and the retriever version). Running the same retriever into the same collection again updates those documents in place. The written documents are billed as document writes. The response's written_to reports the collection and the number written. Not available with stream=true. To keep a collection filled from a retriever continuously, give the collection a transform that names the retriever instead. examples: - col_shortlist explain: type: boolean title: Explain description: >- OPTIONAL. When true, the response includes `explain_plan` — the query profile for THIS execution: per-stage timings + input/output counts, MVS execution stats, and the optimizer summary (and, once wired, the shard ExecutionTrace: chosen legs, fusion, push-downs, nprobe, served/shadow planner). Analogous to SQL `EXPLAIN ANALYZE` — the query still runs and returns documents; the plan is attached alongside. The same profile is auto-logged for every execution regardless of this flag (so Studio can read it); `explain=true` simply returns it inline in the response. default: false type: object title: ExecuteRetrieverRequest description: |- Request to execute a retriever with optional streaming support. Inherits all fields from RetrieverExecutionRequest including: - inputs: Runtime input values matching the retriever's input_schema - pagination: Pagination configuration (cursor, offset, etc.) - stream: Enable SSE streaming for real-time stage updates Streaming Execution (stream=True): When streaming is enabled, the response uses Server-Sent Events (SSE) format with Content-Type: text/event-stream. Each stage emits events as it executes: Event Types: - stage_start: Emitted when a stage begins execution - stage_complete: Emitted when a stage finishes with results - stage_error: Emitted if a stage encounters an error - execution_complete: Emitted after all stages finish successfully - execution_error: Emitted if the entire execution fails Each event is a StreamStageEvent containing: - event_type: The type of event - execution_id: Unique execution identifier - stage_name: Human-readable stage name - stage_index: Zero-based stage position - total_stages: Total number of stages - documents: Intermediate results (for stage_complete) - statistics: Stage metrics (duration, counts, etc.) - budget_used: Cumulative resource consumption Example streaming client: ```python response = requests.post( '/v1/retrievers/{id}/execute', json={'inputs': {...}, 'stream': True}, stream=True ) for line in response.iter_lines(): if line.startswith(b'data: '): event = json.loads(line[6:]) print(f"{event['event_type']}: {event.get('stage_name')}") ``` Standard Execution (stream=False, default): Returns a single ExecuteRetrieverResponse with final documents, pagination, and aggregate statistics after all stages complete. examples: - description: Simple query inputs: query: artificial intelligence trends top_k: 25 - description: Query with stage-driven filtering via inputs inputs: categories: - AI - ML min_score: 0.7 published_after: '2024-01-01' query: machine learning top_k: 100 - description: Advanced query with multiple input parameters inputs: date_range: end: '2024-12-31' start: '2024-01-01' query: customer testimonials sentiment: positive top_k: 20 - description: Infinite scroll with cursor pagination (first page) inputs: query: AI trends top_k: 50 pagination: limit: 20 method: cursor - description: Infinite scroll (next page using cursor from previous response) inputs: query: AI trends top_k: 50 pagination: cursor: eyJvZmZzZXQiOjIwfQ== limit: 20 method: cursor - description: Traditional pagination with page numbers inputs: query: ML papers pagination: method: offset page_number: 2 page_size: 25 - description: High-performance keyset pagination inputs: query: customer reviews top_k: 100 pagination: after: id: doc_20 score: 0.73 limit: 20 method: keyset - description: Scroll pagination for bulk export inputs: query: all documents pagination: limit: 100 method: scroll scroll_ttl: 300 ExecuteRetrieverResponse: properties: retriever_id: type: string title: Retriever Id description: >- The retriever that was executed. Use this to link interactions back to the retriever for learned fusion. default: '' examples: - ret_abc123def456 execution_id: type: string title: Execution Id description: >- 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. examples: - exec_abc123def456 - exec_xyz789 status: type: string title: Status description: >- REQUIRED. Execution status indicating current state. Common values: 'completed', 'failed', 'processing', 'pending'. Check this field to determine if execution succeeded or requires retry. examples: - completed - failed - processing degraded: items: $ref: '#/components/schemas/DegradedEntry' type: array title: Degraded description: >- What this run skipped, one entry per resource, when status is 'degraded': the resource kind, its id, why it was skipped, and what to do about it. Empty on a clean run. A degraded run may return few or no documents; read these before treating an empty result as a real no-match. limits: anyOf: - items: $ref: '#/components/schemas/LimitEntry' type: array - type: 'null' title: Limits description: >- OPTIONAL. Every cap that clamped this request: the setting, the value asked for, the value used, the cap's maximum and the stage that applied it. Absent when nothing was capped. A run that hit a cap can return fewer documents than asked; read this before treating a short result as everything that matched. documents: items: additionalProperties: true type: object type: array title: Documents description: >- REQUIRED. Final document results after retriever completion, and the canonical result key: read `documents`, not `results` (the latter is a deprecated byte-for-byte alias, off unless include_legacy_results=true, and its ABSENCE on a normal response must not be read as zero results). 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. The moment_group reduce stage annotates each document with a `moments` array of merged time ranges; each moment has start_ms, end_ms, duration_ms, score, match_count and document_ids (see the moment-annotated example). Empty array indicates no documents matched the query criteria. Note: Legacy format may use 'final_results' instead of 'documents'. examples: - - document_id: doc_123 payload: metadata: category: AI text: Sample content score: 0.95 - document_id: doc_456 payload: metadata: category: ML text: Another document score: 0.88 - document_id: moment_vid_A_12000 moments: - document_ids: - frame_41 - frame_42 - frame_43 duration_ms: 6500 end_ms: 18500 match_count: 3 score: 0.91 start_ms: 12000 parent_id: vid_A score: 0.91 results: items: additionalProperties: true type: object type: array title: Results description: >- DEPRECATED alias for `documents`. Previously a computed field that duplicated `documents` byte-for-byte in every response (~half the payload). It is no longer populated by default to cut response size; pass `?include_legacy_results=true` to restore it during migration. Prefer `documents` — it is and has always been the canonical field. OMITTED from the response when unpopulated while `documents` has data (an empty `results` next to populated `documents` misled readers into 'no results' — 2026-07-06 and again 2026-07-08). When present it is ALWAYS a JSON array, never null. See FRUSTRATIONS.md 2026-04-02 / 2026-06-29 / 2026-06-30. deprecated: true pagination: additionalProperties: true type: object title: Pagination description: >- REQUIRED. Pagination metadata structure. Format varies by pagination method: Offset: {method, page_number, page_size, returned, total, has_next}, Cursor: {method, limit, returned, total, cursor, has_next}, Scroll: {method, scroll_id, limit, returned, total, has_next}, Keyset: {method, limit, returned, total, after}. Every method reports 'total', the number of documents the pipeline computed for this execution BEFORE the page slice, so compare total against returned to detect that a page is a subset. Use this to navigate through result pages. examples: - has_next: false limit: 25 method: cursor returned: 25 total: 25 - has_next: true method: offset page_number: 1 page_size: 10 returned: 10 total: 40 stage_statistics: $ref: '#/components/schemas/RetrieverExecutionStatistics' description: >- 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. facets: anyOf: - items: additionalProperties: true type: object type: array - type: 'null' title: Facets description: >- Facet value-lists + counts computed by the feature_search stage(s), surfaced at the TOP LEVEL for discoverability: each entry is a FacetResult (a facet `key` plus value/count buckets). The same data also appears per-stage under `stage_statistics.stages..metadata.facets`; this field is the predictable place a facet consumer looks. When more than one stage computes facets, the last stage's facets are surfaced here. None when no facets were requested. budget: additionalProperties: true type: object title: Budget description: >- REQUIRED. This run's usage: credits_used, credits_limit, time_elapsed_ms, time_limit_ms, tokens_used, llm_calls, metering. credits_used is what was charged to this run; a plain text search and a cache hit read 0.0. metering is 'unmetered' where there is no billing path, and credits_used is no price. examples: - credits_used: 0 llm_calls: 0 metering: metered cached_at: anyOf: - type: number - type: 'null' title: Cached At description: >- Unix timestamp when this result was stored in the retriever cache. Present (non-null) only on cache hits; null on fresh executions, so a caller can tell how old a cached page is. completeness: anyOf: - additionalProperties: type: string type: object - type: 'null' title: Completeness description: >- Completeness by layer, so the claims never contradict: `embeddings` is complete, complete_after_retry or partial (some query embeddings were dropped); `page` is complete, not_known_complete (a retried stage answered an empty page) or the execution status; `overall` is complete only when both layers are. Filled in when the response is written. warnings: items: type: string type: array title: Warnings description: >- OPTIONAL. Execution warnings that did not prevent results but indicate potential issues — e.g. filtering on unindexed fields. Empty when there are no warnings. interpretation: anyOf: - additionalProperties: true type: object - type: 'null' title: Interpretation description: >- OPTIONAL. What the platform UNDERSTOOD from your request, so a correction or relaxation is visible instead of silent. Keys: provided_input_keys (the inputs you sent), inferred_inputs (schema defaults applied because you omitted the field — name: value), ignored_input_keys (inputs nothing in the pipeline consumes; they had no effect), and relaxations (filter conditions removed because the input they reference was not provided — each names the field, the template, and where it sat; the result set is BROADER than the literal filter when this is non-empty). The literal query text is used AS PROVIDED — no spell-correction step exists; semantic search is typo-tolerant by embedding, which this block does not alter. Stage-level rewrites (e.g. query_expand) report their expansions in stage_statistics.stages..metadata. error: anyOf: - type: string - type: 'null' title: Error description: >- 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. examples: - 'Retriever execution failed: Collection not found' - 'Budget exceeded: Maximum credits limit reached' optimization_applied: type: boolean title: Optimization Applied description: >- 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. default: false examples: - true - false optimization_summary: anyOf: - additionalProperties: true type: object - type: 'null' title: Optimization Summary description: >- 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. examples: - 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 - optimization_time_ms: 2.1 optimized_stage_count: 3 original_stage_count: 3 rules_applied: [] stage_reduction_pct: 0 learned_fusion_context: anyOf: - additionalProperties: true type: object - type: 'null' title: Learned Fusion Context description: >- OPTIONAL. Learned fusion context when the retriever uses learned fusion (auto-tune) for weight optimization. Contains: context_key (resolution level used), sampled_weights (per-feature weight vector), feature_uris (features that were weighted), effective_exploration (Thompson sampling exploration rate), context_level ('personal', 'segment', or 'global'). Only present when learned fusion is active on this retriever. written_to: anyOf: - additionalProperties: true type: object - type: 'null' title: Written To description: >- Present when the request named target_collection_id: the collection_id written to, documents_written, and documents_skipped (results with no document id, which cannot be written). cache_hit: type: boolean title: Cache Hit description: >- True when this response was served from the retriever-level execute cache (cached_at then carries the storage timestamp); false on fresh executions. This is the canonical cache-hit signal: prefer it over inferring a hit from per-stage statistics, which on a cache hit reflect the original fresh run and read as cache_hit:false. default: false consistency_mode: anyOf: - type: string - type: 'null' title: Consistency Mode description: >- Which read consistency served this execution. 'strong': the read saw every write acknowledged before it, including the write named by a write_token. 'eventual': the read may miss a recent write. A replica usually catches up within seconds, but a page computed while it was behind is cached, and can keep missing that write until the next write to the collections it reads or until the cached page expires, one hour by default. To read past a cached page, send a write_token, set consistency.mode to 'strong', or set skip_cache to true. Set from the request's consistency.mode, a write_token, or the deployment default. enrichment_skipped: type: boolean title: Enrichment Skipped description: Whether any enrichment stages were skipped due to credit limits. default: false enrichment_skipped_stages: items: type: string type: array title: Enrichment Skipped Stages description: Names of enrichment stages that were skipped. enrichment_skip_reason: anyOf: - type: string - type: 'null' title: Enrichment Skip Reason description: Reason enrichment stages were skipped (e.g., credit limit reached). diagnostics: anyOf: - additionalProperties: true type: object - type: 'null' title: Diagnostics description: >- Agent-facing self-debugging aid: a human summary, per-stage input/output counts, and next_actions. Populated especially when a filter stage reduces candidates to zero so a caller can tell whether the field path was wrong, the field was absent, or values simply did not match — instead of guessing at a silent empty result. explain_plan: anyOf: - additionalProperties: true type: object - type: 'null' title: Explain Plan description: >- Query profile for this execution, populated only when the request set `explain=true`: per-stage timings and input/output counts, MVS execution stats and the optimizer summary. `spans` lists each timed block of the request (phases, stages, MVS, Mongo and Redis calls) with `wall_ms`, `cpu_ms` and `exclusive`; `cpu_ms` is the request's own only when `exclusive` is true. The profile without spans is also logged as a `retriever_query_profile` event. Additive: tolerate new keys. type: object required: - execution_id - status title: ExecuteRetrieverResponse description: >- Response from retriever execution (non-streaming mode). This response is returned when stream=False (the default). For streaming execution, the response is a Server-Sent Events stream of StreamStageEvent objects instead of this model. Contains: - execution_id: Unique identifier for this execution - status: Execution status ('completed', 'failed', etc.) - documents: Final document results after all stages complete - pagination: Pagination metadata for result navigation - stage_statistics: Per-stage execution metrics - budget: Resource consumption (credits, time, tokens) - optimization_applied: Whether pipeline was optimized - optimization_summary: Details of optimization transformations For streaming responses (stream=True), see StreamStageEvent model which contains event_type, stage progress, intermediate results, and statistics as each stage executes. 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 OffsetPaginationParams: properties: method: type: string const: offset title: Method description: Constant identifying offset pagination (REQUIRED). default: offset page_size: type: integer maximum: 500 minimum: 1 title: Page Size description: 'Number of documents per page (REQUIRED). Default: 10.' default: 10 page_number: type: integer minimum: 1 title: Page Number description: '1-based page index to retrieve (REQUIRED). Default: 1.' default: 1 type: object title: OffsetPaginationParams description: |- Offset-based pagination using page number sizing. Best for: Traditional page UIs with page number navigation How it works: - Uses page numbers (1, 2, 3...) and page size - Calculates offset as: (page_number - 1) * page_size - Simple and familiar for users - Can jump to any page directly Tradeoffs: - Can have "page drift" if data changes between requests - Example: Items added/deleted causes duplicates or gaps - Less efficient for large offsets (database must skip N rows) Use when: - Building traditional page-numbered UIs - Users need to jump to specific pages - Result set is relatively stable - Working with smaller datasets Example: Page 1: {"method": "offset", "page_size": 25, "page_number": 1} Page 2: {"method": "offset", "page_size": 25, "page_number": 2} CursorPaginationParams: properties: method: type: string const: cursor title: Method description: Constant identifying cursor pagination (REQUIRED). default: cursor limit: type: integer maximum: 500 minimum: 1 title: Limit description: >- Maximum number of documents to return per page (REQUIRED). Default: 10. default: 10 cursor: anyOf: - type: string - type: 'null' title: Cursor description: >- Opaque base64 cursor from previous response (OPTIONAL). null for first page, then use cursor from response.pagination.cursor type: object title: CursorPaginationParams description: >- Cursor-based pagination referencing last seen position. Best for: Infinite scroll UIs, mobile apps, real-time feeds How it works: - First request: cursor=null - Response includes next cursor token - Next request: pass cursor from previous response - Stateless: no server-side state - Consistent: no duplicates/gaps even with concurrent writes Use when: - Building infinite scroll interfaces - Users scroll through results sequentially - You need consistency across pages - You don't need to jump to arbitrary pages Example flow: 1. Request: {"method": "cursor", "limit": 20, "cursor": null} 2. Response: {"documents": [...], "pagination": {"cursor": "abc123", "has_next": true}} 3. Request: {"method": "cursor", "limit": 20, "cursor": "abc123"} ScrollPaginationParams: properties: method: type: string const: scroll title: Method description: Constant identifying scroll pagination (REQUIRED). default: scroll limit: type: integer maximum: 1000 minimum: 1 title: Limit description: >- Number of documents to fetch per scroll page (REQUIRED). Default: 100. default: 100 scroll_id: anyOf: - type: string - type: 'null' title: Scroll Id description: >- Server-issued scroll session identifier (OPTIONAL). null for first request, then use scroll_id from response scroll_ttl: type: integer maximum: 3600 minimum: 60 title: Scroll Ttl description: >- Seconds to keep scroll context alive (REQUIRED). Default: 300 (5 minutes). default: 300 type: object title: ScrollPaginationParams description: >- Scroll-style pagination maintaining server-side context for TTL. Best for: Bulk exports, batch processing, iterating through all results How it works: - Server maintains a snapshot of results - First request: scroll_id=null, returns scroll_id - Subsequent requests: use scroll_id from response - Context expires after scroll_ttl seconds - Consistent view of data (point-in-time snapshot) Tradeoffs: - Requires server-side state (memory/cache) - TTL means sessions can expire - Not suitable for long-lived sessions - Good for background jobs, not user-facing UIs Use when: - Exporting large datasets - Batch processing all results - Background jobs iterating through results - You need consistent point-in-time view Example flow: 1. Request: {"method": "scroll", "limit": 100, "scroll_id": null} 2. Response: {"documents": [...], "scroll_id": "xyz789", "has_next": true} 3. Request: {"method": "scroll", "limit": 100, "scroll_id": "xyz789"} KeysetPaginationParams: properties: method: type: string const: keyset title: Method description: Constant identifying keyset pagination (REQUIRED). default: keyset limit: type: integer maximum: 500 minimum: 1 title: Limit description: >- Maximum number of documents to return per page (REQUIRED). Default: 10. default: 10 after: anyOf: - additionalProperties: true type: object - type: 'null' title: After description: >- Last seen keyset marker from previous response (OPTIONAL). Must include all sort fields. Example: {'score': 0.73, 'id': 'doc_20'}. null for first page, then use next_cursor from response type: object title: KeysetPaginationParams description: >- Stateless keyset pagination relying on last seen sort key. Best for: High-performance pagination, large result sets, stable sorting How it works: - Uses actual field values as pagination markers - Database can use indexes efficiently (WHERE score < 0.73) - No offset calculation or server state - Requires deterministic sort order (e.g., score DESC, id ASC) - Most efficient pagination method Requirements: - Results must be sorted consistently - Sort fields must be in the "after" marker - Example: sorted by (score DESC, id ASC) → after: {score: 0.73, id: "doc_20"} Advantages: - No server-side state (truly stateless) - Consistent even with concurrent writes - Database can use indexes (fast for large datasets) - No offset performance degradation Use when: - You have stable, deterministic sort fields - Working with large result sets (10k+ docs) - Maximum performance is critical - You need infinite scroll with best efficiency Example flow: 1. Request: {"method": "keyset", "limit": 20, "after": null} 2. Response: {"documents": [...], "next_cursor": {"score": 0.85, "id": "doc_20"}} 3. Request: {"method": "keyset", "limit": 20, "after": {"score": 0.85, "id": "doc_20"}} ReadConsistencyOption: properties: mode: type: string enum: - strong - eventual title: Mode description: >- 'strong': the read sees every write acknowledged before it. 'eventual': the read may be served from a replica or a cached page and miss recent writes, in exchange for lower latency and less load on primaries. consistency_mode on the response says for how long. max_staleness_ms: anyOf: - type: integer minimum: 0 - type: 'null' title: Max Staleness Ms description: >- With mode='eventual', the most a serving replica may lag the primary, in milliseconds. A replica further behind is skipped and the read goes to the primary. Ignored for 'strong'. type: object required: - mode title: ReadConsistencyOption description: How fresh a retriever read must be (plan 6.14). DegradedEntry: properties: resource: type: string title: Resource description: >- Kind of resource skipped: stage, collection, taxonomy, retriever, namespace. examples: - taxonomy id: anyOf: - type: string - type: 'null' title: Id description: Identifier of the skipped resource, when it has one. examples: - tax_abc123 reason: type: string title: Reason description: Why it was skipped. examples: - not found in namespace next_step: type: string title: Next Step description: What the caller can do about it. examples: - Fix the taxonomy_id on the stage, or create the taxonomy. stage: anyOf: - type: string - type: 'null' title: Stage description: The stage that skipped it, when a stage did. type: object required: - resource - reason - next_step title: DegradedEntry description: |- One resource a response could not include (plan 6.16). The same shape 6.10's degradation contract uses for its stage and arm entries, so a client reads one structure for every kind of skip. LimitEntry: properties: name: type: string title: Name description: The setting that was capped. examples: - final_top_k - pagination_depth requested: type: integer title: Requested description: The value the request asked for. examples: - 2000 applied: type: integer title: Applied description: The value the platform used. examples: - 500 ceiling: type: integer title: Ceiling description: The cap's maximum for this setting. examples: - 500 stage: anyOf: - type: string - type: 'null' title: Stage description: The stage that applied the cap, when a stage did. type: object required: - name - requested - applied - ceiling title: LimitEntry description: >- One cap that clamped a request (plan 6.10's ``limits``). Reported when the platform applied a smaller value than the request asked for, so a short result reads as the cap rather than as a no-match. RetrieverExecutionStatistics: properties: stages: additionalProperties: $ref: '#/components/schemas/StageStatistics' type: object title: Stages description: Per-stage statistics keyed by stage instance name (REQUIRED). total_time_ms: type: number minimum: 0 title: Total Time Ms description: Total retriever execution time in milliseconds (REQUIRED). default: 0 credits_used: type: number minimum: 0 title: Credits Used description: Same value as budget.credits_used on an execute response. default: 0 server_service_ms: anyOf: - type: number minimum: 0 - type: 'null' title: Server Service Ms description: >- Controller-measured service span in ms: the wall time of the service.execute_retriever call, stamped by the API controller after execution. Partitions request latency beyond the stages: middleware total minus this = pre-body (DI/auth/tenant resolution); this minus the stage sum = service-outside-stages (cache lookup, plan build, serialization). None on cache-hit replays, whose statistics belong to a different execution. type: object title: RetrieverExecutionStatistics description: Aggregated execution statistics for an entire retriever execution run. 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. StageStatistics: properties: input_count: type: integer minimum: 0 title: Input Count description: Number of documents received by the stage (REQUIRED). output_count: type: integer minimum: 0 title: Output Count description: Number of documents emitted by the stage (REQUIRED). duration_ms: type: number minimum: 0 title: Duration Ms description: Wall-clock duration in milliseconds (REQUIRED). efficiency: type: number minimum: 0 title: Efficiency description: Output/Input ratio. 0 when input_count is 0 (REQUIRED). cache_hit: anyOf: - type: boolean - type: 'null' title: Cache Hit description: >- Deprecated alias for stage_cache_hit, kept for existing callers (OPTIONAL). Despite the name, this describes only THIS stage's own cache, not the retriever-level execute cache reported by cache_hit on the top-level response -- the two fields have shared this name across different response levels and that has misled multiple verification passes. Prefer stage_cache_hit. stage_cache_hit: anyOf: - type: boolean - type: 'null' title: Stage Cache Hit description: >- Indicates whether THIS stage served its result from its own stage cache (OPTIONAL). Distinct from cache_hit on the top-level retriever execution response, which describes a separate, retriever-level execute cache; a stage can report stage_cache_hit=true on a response whose top-level cache_hit is false, and that is not a contradiction. cached_at: anyOf: - type: number - type: 'null' title: Cached At description: >- Unix timestamp when this stage result was cached. Present only on cache hits. error: anyOf: - type: string - type: 'null' title: Error description: >- Stage-specific error message if execution failed but retriever execution continued (OPTIONAL). llm_calls: anyOf: - type: integer minimum: 0 - type: 'null' title: Llm Calls description: Number of LLM invocations performed by the stage (OPTIONAL). tokens_used: anyOf: - type: integer minimum: 0 - type: 'null' title: Tokens Used description: Total tokens consumed by the stage (OPTIONAL, only for LLM stages). metadata: additionalProperties: true type: object title: Metadata description: >- Stage-specific metadata containing additional execution details (OPTIONAL). For example, join stages include: join_strategy, join_type, matched_count, match_rate, etc. LLM stages may include: model_name, temperature, max_tokens, etc. type: object required: - input_count - output_count - duration_ms - efficiency title: StageStatistics description: Execution metrics for a single stage in a retriever execution run. examples: - cache_hit: false duration_ms: 123.4 efficiency: 0.05 input_count: 5000 output_count: 250 stage_cache_hit: false securitySchemes: BearerAuth: type: http scheme: bearer description: >- Mixpeek API key, sent as `Authorization: Bearer mxp_sk_...`. Create one in Studio under Settings → API Keys, or with an admin key via `POST /v1/organizations/users/{user_email}/api-keys`. A missing, malformed, unknown, revoked, inactive or expired key returns 401; a key without the permission, scope or plan an operation needs returns 403. NamespaceHeader: type: apiKey in: header name: X-Namespace description: >- Namespace id (`ns_...`), not the namespace name. This scopes the request rather than authenticating it, and it is required on every operation marked `x-mixpeek-namespace-scoped`. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.