---
title: "Execute Adhoc Retriever"
method: POST
path: "/v1/retrievers/execute"
tags: ["Adhoc Retrievers"]
---

# Execute Adhoc Retriever

`POST /v1/retrievers/execute`

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

## Query parameters

- `return_presigned_urls` boolean
- `return_vectors` boolean

## Request body

- AdhocExecuteRequest — 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 }
  - `collection_identifiers` string[] — 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.
  - `input_schema` object — 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.
  - `stages` StageConfigInput[], required — REQUIRED. Ordered list of stage configurations. At least one stage is required for execution.
    - `stage_name` string, required — Human-readable stage instance name (REQUIRED).
    - `stage_type` 'filter' | 'sort' | 'reduce' | 'apply' | 'enrich' — 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)
    - `config` object, required — 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` string, nullable — 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` string, nullable — User-facing description of the stage (OPTIONAL).
    - `on_error` string, nullable — 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` string, nullable — Optional alias to persist this stage's results in the execution context. When set, results are stored in CONTEXT.<alias> in addition to replacing current_results. Downstream stages can reference them via {{CONTEXT.<alias>}} 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).
  - `inputs` object — 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.
  - `budget_limits` BudgetLimits — User-defined limits for time and credits during execution.
    - `max_credits` number, nullable — Maximum credits allowed for a single execution (OPTIONAL).
    - `max_time_ms` integer, nullable — Maximum wall-clock time in milliseconds before forcing halt (OPTIONAL).
  - `stream` boolean — 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

## Response `200`

Successful Response

- unknown

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not Found
- `422` — Validation Error
- `500` — Internal Server Error

---

[API](https://skmtc.net/mixpeek/apis/mixpeek-api.md) · [All operations](https://skmtc.net/mixpeek/apis/mixpeek-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/mixpeek/mixpeek-api/versions/220a3b263fda/schema)