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.

Caching: this route does not use the retriever-level execute cache, so cache_status is always disabled and there is no skip_cache parameter.

That does NOT mean every response is freshly computed. Individual stages keep their own caches, which this route cannot switch off, so a stage may serve a cached result and report cache_hit: true under stage_statistics.stages[*] on a response whose top-level cache_status reads disabled. The two fields describe different caches. If you need a guaranteed fresh execution, persist the retriever (POST /retrievers) and call /retrievers/{id}/execute with skip_cache, which this route lacks and which does reach the stages.

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

Execute Adhoc Retriever

cURL

curl --request POST \
  --url https://api.mixpeek.com/v1/retrievers/execute \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Namespace: <api-key>' \
  --data '
{
  "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"
    }
  ],
  "collection_identifiers": [
    "my_collection"
  ],
  "input_schema": {
    "query": {
      "description": "Search query",
      "required": true,
      "type": "text"
    }
  },
  "inputs": {
    "query": "machine learning"
  },
  "filters": {
    "AND": [
      {
        "field": "brand",
        "operator": "eq",
        "value": "Acme"
      }
    ]
  },
  "budget_limits": {
    "max_credits": 100,
    "max_time_ms": 60000
  },
  "pagination": null,
  "limit": null,
  "stream": false
}
'

400

{
  "error": {
    "details": {
      "id": "ns_123",
      "resource": "namespace"
    },
    "message": "Namespace not found",
    "type": "NotFoundError"
  },
  "status": 404,
  "success": false
}

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.

Query Parameters

return_presigned_urls · boolean · default: false

return_vectors · boolean · default: false

Body

application/json

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

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:

Event Types:
- stage_start: Emitted when a stage begins execution
- stage_complete: Emitted when a stage finishes with results
- stage_error: Emitted if a stage encounters an error
- execution_complete: Emitted after all stages finish successfully
- execution_error: Emitted if the entire execution fails

Each event is a StreamStageEvent containing:
- event_type: The type of event
- execution_id: Unique execution identifier
- stage_name: Human-readable stage name
- stage_index: Zero-based stage position
- total_stages: Total number of stages
- documents: Intermediate results (for stage_complete)
- statistics: Stage metrics (duration_ms, input_count, output_count, etc.)
- budget_used: Cumulative resource consumption (credits, time, tokens)

Response Headers (streaming):
- Content-Type: text/event-stream
- Cache-Control: no-cache
- Connection: keep-alive
- X-Execution-Mode: adhoc

Example streaming request:
```python
response = requests.post(
    '/v1/retrievers/execute',
    json={
        'collection_identifiers': ['my_collection'],
        'input_schema': {'query': {'type': 'text', 'required': True}},
        'stages': [...],
        'inputs': {'query': 'machine learning'},
        'stream': True
    },
    stream=True
)
for line in response.iter_lines():
    if line.startswith(b'data: '):
        event = json.loads(line[6:])
        print(f"{event['event_type']}: {event.get('stage_name')}")
```

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

Show child attributes

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:

["my_collection"]

["col_abc123", "products"]

[]

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.

Show child attributes

Examples:

{
  "query": {
    "description": "Search query",
    "required": true,
    "type": "text"
  }
}

{
  "query": { "required": true, "type": "text" },
  "top_k": { "required": false, "type": "integer" }
}

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:

{ "query": "machine learning" }

{ "query": "AI trends", "top_k": 50 }

filters · Filters · object | null

OPTIONAL. Execute-time filters applied to the document search, the same key the by-id execute request accepts. Merged (AND) with any pre_filters already set inside the 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. A top-level 'pre_filters' is accepted as an alias.

Example:

{
  "AND": [
    {
      "field": "brand",
      "operator": "eq",
      "value": "Acme"
    }
  ]
}

budget_limits · BudgetLimits · object | null

OPTIONAL. Budget limits for execution.

Show child attributes

Example:

{ "max_credits": 100, "max_time_ms": 60000 }

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}

OffsetPaginationParams

CursorPaginationParams

ScrollPaginationParams

KeysetPaginationParams

Show child attributes

Example:

null

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. Honored only when 'pagination' is absent, as on the by-id execute request; the response's pagination cursor fetches the next page. 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 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

200

application/json

Successful Response