Sign in

v5

latestOpenAPI 3.1.02026-08-025631,1012.8 MB
Adhoc Retrievers

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

post/v1/retrievers/execute

Query parameters

return_presigned_urlsboolean
return_vectorsboolean

Request body

collection_identifiersstring[]

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_schemaobject

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.

inputsobject

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.

streamboolean

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

Example request

{
  "collection_identifiers": [
    "my_collection"
  ],
  "input_schema": {
    "query": {
      "description": "Search query",
      "required": true,
      "type": "text"
    }
  },
  "stages": [
    {
      "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"
    }
  ],
  "inputs": {
    "query": "machine learning"
  },
  "budget_limits": {
    "max_credits": 100,
    "max_time_ms": 60000
  }
}

Response

Successful Response

{"stackTrail":"paths:/v1/retrievers/execute:post:responses:200:content:application/json:schema","oasType":"schema","type":"unknown"}