Skip to main content
POST
Execute Adhoc Retriever

Authorizations

​
Authorization
string
header
required

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 header returns 403; an invalid or revoked key returns 401.

​
X-Namespace
string
header
required

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.

Query Parameters

​
return_presigned_urls
boolean
default:false
​
return_vectors
boolean
default:false

Body

application/json

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:

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 }

​
stages
StageConfig · object[]
required

REQUIRED. Ordered list of stage configurations. At least one stage is required for execution.

Minimum array length: 1
​
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.

Examples:
​
input_schema
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.

Examples:
​
inputs
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.

Examples:
​
budget_limits
BudgetLimits · object | null

OPTIONAL. Budget limits for execution.

Example:
​
pagination
OffsetPaginationParams · object

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}

Example:

null

​
limit
integer | null
deprecated

DEPRECATED alias for the pagination page size, honored only when 'pagination' is absent — mirrors the by-id execute request. Previously silently ignored on adhoc bodies (BACKE-3445).

Required range: 1 <= x <= 100
Example:

null

​
stream
boolean
default:false

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
Examples:

false

true

Response

Successful Response