Execute Retriever (Auto-Optimized)

DEPRECATED alias for the pagination page size — prefer 'pagination' (e.g. {"method": "cursor", "limit": 100}). Previously accepted-and-IGNORED: results silently capped at the default page size (10) regardless of the value, and out-of-range values didn't even 422 (FRUSTRATIONS 2026-07-23). Now: when 'pagination' is absent, 'limit' is honored as the default cursor pagination's page size; when both are provided and disagree, pagination wins and a top-level response warning names the conflict.

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

const eventSource = new EventSource('/v1/retrievers/ret_123/execute?stream=true');
eventSource.onmessage = (event) => {
  const stageEvent = JSON.parse(event.data);
  if (stageEvent.event_type === 'stage_complete') {
    console.log(`Stage ${stageEvent.stage_name} completed`);
    console.log(`Documents: ${stageEvent.documents.length}`);
  }
};

Example streaming client (Python):

import requests
response = requests.post('/v1/retrievers/ret_123/execute',
                        json={'inputs': {...}, 'stream': True},
                        stream=True)
for line in response.iter_lines():
    if line.startswith(b'data: '):
        event = json.loads(line[6:])
        print(f"Stage {event['stage_name']}: {event['event_type']}")

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.

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.

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

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.

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.