Execute Public Retriever

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.

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.