> ## 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 Adhoc Retriever > Execute a retriever ad-hoc without persisting the configuration. This endpoint allows you to execute a retriever without saving it to the database. Useful for one-time queries, testing configurations, or temporary searches. Streaming Execution (stream=True): Response uses Server-Sent Events (SSE) format with Content-Type: text/event-stream. Each stage emits events as it executes, formatted as: data: {json}\n\n Event Types (StreamEventType): - stage_start: Emitted when a stage begins (includes stage_name, stage_index, total_stages) - stage_complete: Emitted when a stage finishes (includes documents, statistics, budget_used) - stage_error: Emitted if a stage fails (includes error message) - execution_complete: Final event with complete results and pagination - execution_error: Emitted if entire execution fails StreamStageEvent Fields: - event_type: Type of event - execution_id: Unique execution identifier - stage_name/stage_index/total_stages: Stage progress info - documents: Intermediate results (stage_complete only) - statistics: Stage metrics (duration_ms, input_count, output_count, efficiency) - budget_used: Cumulative consumption (credits_used, time_elapsed_ms, tokens_used) Response Headers: - Content-Type: text/event-stream - Cache-Control: no-cache - Connection: keep-alive - X-Execution-Mode: adhoc Standard Execution (stream=False, default): - Returns ExecuteRetrieverResponse after all stages complete - Includes X-Execution-Mode: adhoc header - execution_metadata.retriever_persisted = False Use Cases: - One-time queries without saving retriever configuration - Testing stage configurations before persisting - Dynamic retrieval with varying parameters - Real-time progress tracking with streaming ## OpenAPI ````yaml post /v1/retrievers/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: [] paths: /v1/retrievers/execute: post: tags: - Adhoc Retrievers summary: Execute Adhoc Retriever description: >- Execute a retriever ad-hoc without persisting the configuration. This endpoint allows you to execute a retriever without saving it to the database. Useful for one-time queries, testing configurations, or temporary searches. Streaming Execution (stream=True): Response uses Server-Sent Events (SSE) format with Content-Type: text/event-stream. Each stage emits events as it executes, formatted as: data: {json}\n\n Event Types (StreamEventType): - stage_start: Emitted when a stage begins (includes stage_name, stage_index, total_stages) - stage_complete: Emitted when a stage finishes (includes documents, statistics, budget_used) - stage_error: Emitted if a stage fails (includes error message) - execution_complete: Final event with complete results and pagination - execution_error: Emitted if entire execution fails StreamStageEvent Fields: - event_type: Type of event - execution_id: Unique execution identifier - stage_name/stage_index/total_stages: Stage progress info - documents: Intermediate results (stage_complete only) - statistics: Stage metrics (duration_ms, input_count, output_count, efficiency) - budget_used: Cumulative consumption (credits_used, time_elapsed_ms, tokens_used) Response Headers: - Content-Type: text/event-stream - Cache-Control: no-cache - Connection: keep-alive - X-Execution-Mode: adhoc Standard Execution (stream=False, default): - Returns ExecuteRetrieverResponse after all stages complete - Includes X-Execution-Mode: adhoc header - execution_metadata.retriever_persisted = False Use Cases: - One-time queries without saving retriever configuration - Testing stage configurations before persisting - Dynamic retrieval with varying parameters - Real-time progress tracking with streaming operationId: execute_adhoc_retriever_v1_retrievers_execute_post parameters: - name: return_presigned_urls in: query required: false schema: type: boolean default: false title: Return Presigned Urls - name: return_vectors in: query required: false schema: type: boolean default: false title: Return Vectors requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AdhocExecuteRequest' 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: AdhocExecuteRequest: properties: collection_identifiers: items: type: string type: array title: Collection Identifiers description: >- Collection identifiers (names or IDs) to query. Can be collection names or IDs. Names are automatically resolved. Can be empty for query-only inference mode (e.g., LLM query analysis without documents). Also accepts 'collection_ids' as an alias for backward compatibility. examples: - - my_collection - - col_abc123 - products - [] input_schema: additionalProperties: $ref: '#/components/schemas/RetrieverInputSchemaField-Input' description: >- Schema definition for this input field. Defines type, description, examples, and validation rules. Supports all bucket types (string, number, image, etc.) plus document_reference. Frontend uses this to render the appropriate input component (text input, image upload, dropdown, etc.) type: object title: Input Schema description: >- OPTIONAL. Input schema defining expected inputs. Each key is an input name, value is a RetrieverInputSchemaField. Omit it (or pass {}) for a stages-only execute whose stages carry hardcoded query values — no dynamic inputs needed. examples: - query: description: Search query required: true type: text - query: required: true type: text top_k: required: false type: integer stages: items: $ref: '#/components/schemas/StageConfig-Input' type: array minItems: 1 title: Stages description: >- REQUIRED. Ordered list of stage configurations. At least one stage is required for execution. inputs: additionalProperties: true type: object title: Inputs description: >- OPTIONAL. Input values matching the input_schema. These values are passed to stages for parameterization. Omit it (or pass {}) when the stages carry hardcoded query values. examples: - query: machine learning - query: AI trends top_k: 50 budget_limits: anyOf: - $ref: '#/components/schemas/BudgetLimits' - type: 'null' description: OPTIONAL. Budget limits for execution. 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 Content-Type: text/event-stream - Events emitted: stage_start, stage_complete, stage_error, execution_complete, execution_error - Each event is formatted as: data: {json}\n\n - StreamStageEvent contains: event_type, execution_id, stage_name, stage_index, total_stages, documents (intermediate), statistics, budget_used When to use streaming: - Progress tracking for multi-stage pipelines - Displaying intermediate results as stages complete - Real-time budget and performance monitoring - Debugging pipeline execution When to skip streaming: - Single-stage or fast pipelines (<100ms) - No need for intermediate results - Minimizing overhead is critical default: false examples: - false - true type: object required: - stages title: AdhocExecuteRequest description: >- Request to execute a retriever ad-hoc without persistence. This combines retriever creation parameters with execution inputs to allow one-time retrieval without saving the retriever configuration. Use Cases: - One-time queries without polluting retriever registry - Testing retriever configurations before persisting - Dynamic retrieval with varying stage configurations - Temporary search operations Behavior: - Retriever is NOT saved to database - Execution history is logged but marked as ad-hoc - Response includes X-Execution-Mode: adhoc header - execution_metadata.retriever_persisted = False 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_ms, input_count, output_count, etc.) - budget_used: Cumulative resource consumption (credits, time, tokens) Response Headers (streaming): - Content-Type: text/event-stream - Cache-Control: no-cache - Connection: keep-alive - X-Execution-Mode: adhoc Example streaming request: ```python response = requests.post( '/v1/retrievers/execute', json={ 'collection_identifiers': ['my_collection'], 'input_schema': {'query': {'type': 'text', 'required': True}}, 'stages': [...], 'inputs': {'query': 'machine learning'}, '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: Simple ad-hoc search: { "collection_identifiers": ["col_123"], "input_schema": {"query": {"type": "text", "required": True}}, "stages": [{ "stage_name": "search", "stage_type": "filter", "config": { "stage_id": "feature_search", "parameters": { "searches": [{ "feature_uri": "mixpeek://text_extractor@v1/embedding", "query": { "input_mode": "text", "text": "{{INPUT.query}}" }, "top_k": 100 }], "final_top_k": 10 } } }], "inputs": {"query": "machine learning"}, "stream": false } 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 RetrieverInputSchemaField-Input: properties: type: $ref: '#/components/schemas/RetrieverInputSchemaFieldType' default: anyOf: - {} - type: 'null' title: Default items: anyOf: - $ref: '#/components/schemas/RetrieverInputSchemaField-Input' - type: 'null' properties: anyOf: - additionalProperties: $ref: '#/components/schemas/RetrieverInputSchemaField-Input' type: object - type: 'null' title: Properties examples: anyOf: - items: {} type: array - type: 'null' title: Examples description: >- OPTIONAL. List of example values for this field. Used by Apps to show example inputs in the UI. Provide multiple diverse examples when possible. description: anyOf: - type: string - type: 'null' title: Description enum: anyOf: - items: {} type: array - type: 'null' title: Enum required: anyOf: - type: boolean - type: 'null' title: Required default: false additionalProperties: true type: object required: - type title: RetrieverInputSchemaField description: >- Schema field definition for retriever input parameters. Identical structure to BucketSchemaField but uses RetrieverInputSchemaFieldType which includes additional reference types like document_reference. This allows retrievers to accept: 1. Metadata inputs (strings, numbers, dates, etc.) 2. File inputs (images, videos, documents for search) 3. Reference inputs (document_reference for "find similar" queries) StageConfig-Input: properties: stage_name: type: string minLength: 1 title: Stage Name description: Human-readable stage instance name (REQUIRED). stage_type: anyOf: - $ref: '#/components/schemas/StageType' - type: 'null' description: >- Functional category of the stage. Optional for creation requests; auto-inferred from `stage_id` when omitted. config: additionalProperties: true type: object title: Config description: >- Stage implementation parameters (REQUIRED). Must include `stage_id` key referencing a registered retriever stage. Supports template expressions using Jinja2 syntax resolved at execution time. Template namespaces support both uppercase and lowercase formats: {{INPUT.field}} or {{inputs.field}}, {{DOC.field}} or {{doc.field}}, {{CONTEXT.field}} or {{context.field}}, {{STAGE.field}} or {{stage.field}}. All formats work identically. Provide stage-specific configuration under `parameters`. Optional `pre_filters` and `post_filters` are placed as SIBLINGS of `parameters` (NOT nested inside). Pre-filters require payload indexes on the filtered fields. batch_size: anyOf: - type: string - type: 'null' title: Batch Size description: >- Optional templated batch size expression evaluated per execution. Supports template variables: {{INPUT.page_size}}, {{inputs.page_size}}, {{CONTEXT.budget_remaining}}, etc. Both uppercase and lowercase namespace names are supported (e.g., INPUT/inputs, DOC/doc, CONTEXT/context, STAGE/stage). Defaults to stage-specific value when omitted. description: anyOf: - type: string - type: 'null' title: Description description: User-facing description of the stage (OPTIONAL). on_error: anyOf: - type: string - type: 'null' title: On Error description: >- Behavior when this stage fails. 'skip' continues execution with results from previous stages (graceful degradation). 'error' (default) fails the entire retriever. Useful for optional enrichment or multi-modal stages where one modality may not apply (e.g., face search on logo-only images). output_alias: anyOf: - type: string - type: 'null' title: Output Alias description: >- Optional alias to persist this stage's results in the execution context. When set, results are stored in CONTEXT. in addition to replacing current_results. Downstream stages can reference them via {{CONTEXT.}} in templates. Useful for multi-stage pipelines where later stages should not overwrite earlier results (e.g., face search + logo search producing independent result sets). type: object required: - stage_name - config title: StageConfig description: >- Configuration for a single stage within a retriever. Stages support dynamic configuration through template expressions using Jinja2 syntax. IMPORTANT - Template Syntax: - Use DOUBLE curly braces: {{INPUT.query}} (correct) - Single curly braces will NOT work: {INPUT.query} (wrong - not substituted) - Namespace names are CASE-INSENSITIVE: {{INPUT.query}}, {{inputs.query}}, {{input.query}} all work identically Template Namespaces (case-insensitive): - INPUT / inputs / input: User-provided query parameters and inputs - DOC / doc: Current document fields (for per-document logic) - CONTEXT / context: Execution state (budget, timing, retriever metadata) - STAGE / stage: Previous stage outputs (for cascading logic) Examples: Correct: {{INPUT.query_text}}, {{inputs.query}}, {{DOC.content_type}} Correct: {{CONTEXT.budget_remaining}}, {{context.budget_remaining}} Wrong: {INPUT.query} - single braces won't be substituted examples: - config: parameters: final_top_k: 25 searches: - feature_uri: >- mixpeek://text_extractor@v1/multilingual_e5_large_instruct_v1 query: input_mode: text value: '{{INPUT.query_text}}' top_k: 100 stage_id: feature_search description: Feature search stage with uppercase template namespace stage_name: semantic_search stage_type: filter - batch_size: '{{20 * inputs.page_size}}' config: parameters: field: metadata.price operator: gt value: '{{inputs.min_price}}' stage_id: attribute_filter description: Attribute filter with lowercase template namespace stage_name: price_filter stage_type: filter - config: parameters: batch_size: '{{CONTEXT.budget_remaining > 50 ? 200 : 50}}' criteria: '{{inputs.quality_criteria}}' field: '{{DOC.media_type == ''image'' ? ''image_url'' : ''video_url''}}' stage_id: llm_filter description: Mixed case templates in same stage stage_name: llm_filter stage_type: filter - config: parameters: final_top_k: 10 searches: - feature_uri: >- mixpeek://web_scraper@v1/jinaai__jina_embeddings_v2_base_code query: input_mode: text value: '{{INPUT.query}}' top_k: 50 pre_filters: AND: - field: doc_type operator: eq value: code stage_id: feature_search description: Feature search with pre_filters (sibling of parameters, NOT inside) stage_name: search_code_blocks stage_type: filter BudgetLimits: properties: max_credits: anyOf: - type: number minimum: 0 - type: 'null' title: Max Credits description: Maximum credits allowed for a single execution (OPTIONAL). max_time_ms: anyOf: - type: integer minimum: 0 - type: 'null' title: Max Time Ms description: >- Maximum wall-clock time in milliseconds before forcing halt (OPTIONAL). type: object title: BudgetLimits description: User-defined limits for time and credits during execution. examples: - max_credits: 100 max_time_ms: 60000 - max_time_ms: 120000 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 input: title: Input ctx: type: object title: Context type: object required: - loc - msg - type title: ValidationError RetrieverInputSchemaFieldType: type: string enum: - string - number - integer - float - boolean - object - array - date - datetime - text - image - audio - video - pdf - excel - document_reference title: RetrieverInputSchemaFieldType description: >- Supported data types for retriever input schema fields. Retriever input schemas define what parameters users can provide when executing a retriever. This includes all bucket schema types plus additional reference types. Types fall into three categories: 1. **Metadata Types** (JSON types): - Standard JSON-compatible types - Examples: string, number, boolean, date - Inherited from BucketSchemaFieldType 2. **File Types** (blobs): - Users can upload files/content as search inputs - Examples: text, image, video, pdf - Inherited from BucketSchemaFieldType 3. **Reference Types** (structured metadata): - Special types for referencing existing documents - Examples: document_reference - Only available in retriever input schemas (NOT in bucket schemas) **DOCUMENT_REFERENCE Usage**: Accept document reference for "find similar" queries. Example - Find similar products retriever: { "reference_product": { "type": "document_reference", "description": "Find products similar to this one", "required": true } } Execution input: { "inputs": { "reference_product": { "collection_id": "col_products", "document_id": "doc_item_123" } } } The system will use the pre-computed features from doc_item_123 to find similar documents without re-processing. StageType: type: string enum: - filter - sort - reduce - apply - enrich title: StageType description: >- Categorisation of stage behaviour within a retrieval flow. These functional categories describe how stages transform the document stream: - FILTER: N → ≤N documents (subset, same schema) - SORT: N → N documents (same docs, different order, same schema) - REDUCE: N → 1 document (aggregation, new schema) - APPLY: N → N or N*M documents (enrichment/expansion, expanded/new schema) - ENRICH: N → N documents (enrichment with computed fields) ````