Skip to main content
POST
Execute Retriever (Auto-Optimized)

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, malformed, unknown, revoked, inactive or expired key returns 401; a key without the permission, scope or plan an operation needs returns 403.

​
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.

Path Parameters

​
retriever_id
string
required

Retriever ID or name. Pipeline will be automatically optimized before execution.

Query Parameters

​
return_presigned_urls
boolean
default:false

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.

​
return_vectors
boolean
default:false

Include vector embeddings in result documents. Also accepted as a body field — if either source is true, vectors are returned.

​
explain
boolean
default:false

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.

​
include_legacy_results
boolean
default:false

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.

​
skip_cache
boolean
default:false

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.

Body

application/json

Keys this body does not declare are refused with 422 extra_forbidden naming the accepted keys (since 2026-11-02).

Execution request with inputs, filters, pagination, and optional stream parameter. Set stream=true to receive real-time stage updates via Server-Sent Events.

​
inputs
Inputs · object

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:
​
filters
Filters · object | null

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.

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}

​
limit
integer | null
deprecated

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.

Required range: 1 <= x <= 500
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 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):

Example streaming client (Python):

Examples:

false

true

​
expand
string[] | null

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).

Example:
​
skip_cache
boolean
default:false

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.

Examples:

false

true

​
return_presigned_urls
boolean
default:false

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.

Examples:

false

true

​
return_vectors
boolean
default:false

Include vector embeddings in result documents. Also accepted as a return_vectors query parameter; if either source is true, vectors are returned.

Examples:

false

true

​
write_token
string | null

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
ReadConsistencyOption · object | null

OPTIONAL. The read consistency for this execution. Omit to use the deployment default. A write_token always reads strong.

​
target_collection_id
string | null

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.

Example:

"col_shortlist"

​
explain
boolean
default:false

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.

Response

Execution results with documents, pagination, statistics, and optimization details. When stream=true, returns Server-Sent Events. When stream=false, returns JSON response.

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.

​
execution_id
string
required

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
string
required

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"

​
retriever_id
string
default:""

The retriever that was executed. Use this to link interactions back to the retriever for learned fusion.

Example:

"ret_abc123def456"

​
degraded
DegradedEntry · object[]

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
LimitEntry · object[] | null

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
Documents · object[]

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'.

Example:
​
results
Results · object[]
deprecated

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.

​
pagination
Pagination · object

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:
​
stage_statistics
RetrieverExecutionStatistics · object

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
Facets · object[] | null

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.<stage>.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
Budget · object

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.

Example:
​
cached_at
number | null

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
Completeness · object | null

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
string[]

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
Interpretation · object | null

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
string | null

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.

Example:

"Retriever execution failed: Collection not found"

​
optimization_applied
boolean
default:false

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.

Examples:

true

false

​
optimization_summary
Optimization Summary · object | null

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.

Example:
​
learned_fusion_context
Learned Fusion Context · object | null

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
Written To · object | null

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
boolean
default:false

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.

​
consistency_mode
string | null

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
boolean
default:false

Whether any enrichment stages were skipped due to credit limits.

​
enrichment_skipped_stages
string[]

Names of enrichment stages that were skipped.

​
enrichment_skip_reason
string | null

Reason enrichment stages were skipped (e.g., credit limit reached).

​
diagnostics
Diagnostics · object | null

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
Explain Plan · object | null

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.