Execute Adhoc Retriever

curl --request POST \
  --url https://api.mixpeek.com/v1/retrievers/execute \
  --header 'Content-Type: application/json' \
  --data '
{
  "input_schema": {},
  "stages": [
    {
      "stage_name": "<string>",
      "config": {},
      "stage_type": "filter",
      "batch_size": "<string>",
      "description": "<string>"
    }
  ],
  "inputs": {},
  "collection_identifiers": [
    "<string>"
  ],
  "budget_limits": {
    "max_credits": 100,
    "max_time_ms": 60000
  },
  "stream": false
}
'

{
  "status": 123,
  "error": {
    "message": "<string>",
    "type": "<string>",
    "details": {}
  },
  "success": false
}

Adhoc

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.

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

retrievers

execute

Execute Adhoc Retriever

curl --request POST \
  --url https://api.mixpeek.com/v1/retrievers/execute \
  --header 'Content-Type: application/json' \
  --data '
{
  "input_schema": {},
  "stages": [
    {
      "stage_name": "<string>",
      "config": {},
      "stage_type": "filter",
      "batch_size": "<string>",
      "description": "<string>"
    }
  ],
  "inputs": {},
  "collection_identifiers": [
    "<string>"
  ],
  "budget_limits": {
    "max_credits": 100,
    "max_time_ms": 60000
  },
  "stream": false
}
'

{
  "status": 123,
  "error": {
    "message": "<string>",
    "type": "<string>",
    "details": {}
  },
  "success": false
}

Headers

Authorization

string

REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.

X-Namespace

string

REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'

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:

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": { "feature_uris": [{ "uri": "urn:embedding:text:bge_base_en_v1_5:1", "input": {"text": "{{inputs.query}}"} }], "limit": 10 } } }], "inputs": {"query": "machine learning"}, "stream": false }

input_schema

Input Schema · object

required

REQUIRED. Input schema defining expected inputs. Each key is an input name, value is a BucketSchemaField.

Show child attributes

input_schema.{key}

BucketSchemaField · object

Schema field definition for bucket objects.

Show child attributes

input_schema.{key}.type

enum<string>

required

Supported data types for bucket schema fields.

Types fall into two categories:

Metadata Types (JSON types):
- Stored as object metadata
- Standard JSON-compatible types
- Not processed by extractors (unless explicitly mapped)
File Types:
- Stored as blobs (files)
- Processed by extractors
- Require actual file content (URL or base64)

Available options:

string,

number,

integer,

float,

boolean,

object,

array,

date,

datetime,

text,

image,

audio,

video,

pdf,

excel

input_schema.{key}.default

unknown

input_schema.{key}.items

unknown

input_schema.{key}.properties

Properties · object

input_schema.{key}.examples

any[] | null

OPTIONAL. List of example values for this field. Used by Apps to show example inputs in the UI. Provide multiple diverse examples when possible.

input_schema.{key}.description

string | null

input_schema.{key}.enum

any[] | null

input_schema.{key}.required

boolean | null

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

stages.stage_name

string

required

Human-readable stage instance name (REQUIRED).

Minimum string length: 1

stages.config

Config · object

required

Stage implementation parameters (REQUIRED). Must include stage_id key referencing a registered retriever stage. Supports template expressions using Jinja2 syntax resolved at execution time. Template namespaces support both uppercase and lowercase formats: {{INPUT.field}} or {{inputs.field}}, {{DOC.field}} or {{doc.field}}, {{CONTEXT.field}} or {{context.field}}, {{STAGE.field}} or {{stage.field}}. All formats work identically. Provide stage-specific configuration under parameters.

stages.stage_type

enum<string> | null

Functional category of the stage. Optional for creation requests; auto-inferred from stage_id when omitted.

Available options:

filter,

sort,

reduce,

apply,

enrich

stages.batch_size

string | null

Optional templated batch size expression evaluated per execution. Supports template variables: {{INPUT.page_size}}, {{inputs.page_size}}, {{CONTEXT.budget_remaining}}, etc. Both uppercase and lowercase namespace names are supported (e.g., INPUT/inputs, DOC/doc, CONTEXT/context, STAGE/stage). Defaults to stage-specific value when omitted.

stages.description

string | null

User-facing description of the stage (OPTIONAL).

inputs

Inputs · object

required

REQUIRED. Input values matching the input_schema. These values are passed to stages for parameterization.

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

budget_limits

BudgetLimits · object

OPTIONAL. Budget limits for execution.

Show child attributes

budget_limits.max_credits

number | null

Maximum credits allowed for a single execution (OPTIONAL).

Required range: x >= 0

budget_limits.max_time_ms

integer | null

Maximum wall-clock time in milliseconds before forcing halt (OPTIONAL).

Required range: x >= 0

Example:

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

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

Response

Successful Response

Get evaluation results List Adhoc Executions

⌘I

Health

Organizations

Namespaces

Buckets

Feature Extractors

Collections

Retrievers

Taxonomies

Clusters

Templates

Analytics

Resource Search

Inference

Agent Sessions

Tasks

Webhooks

Notifications

Triggers

Execute Adhoc Retriever

Headers

Body

Response