Skip to main content
POST
/
v1
/
retrievers
/
execute
Execute Anonymous Retriever
curl --request POST \
  --url https://api.mixpeek.com/v1/retrievers/execute \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Namespace: <x-namespace>' \
  --data '{
  "collection_identifiers": [
    "my_collection"
  ],
  "input_schema": {
    "query": {
      "description": "Search query",
      "required": true,
      "type": "text"
    }
  },
  "stages": [
    {
      "config": {
        "parameters": {
          "feature_uri": "mixpeek://text_extractor@v1/embedding",
          "query_text": "{{INPUT.query_text}}",
          "top_k": 100
        },
        "stage_id": "hybrid_search"
      },
      "description": "Hybrid search stage with uppercase template namespace",
      "stage_name": "semantic_search",
      "stage_type": "filter"
    }
  ],
  "inputs": {
    "query": "machine learning"
  },
  "budget_limits": {
    "max_credits": 100,
    "max_time_ms": 60000
  }
}'
{
  "execution_id": "exec_abc123def456",
  "status": "completed",
  "documents": [
    {
      "document_id": "doc_123",
      "payload": {
        "metadata": {
          "category": "AI"
        },
        "text": "Sample content"
      },
      "score": 0.95
    },
    {
      "document_id": "doc_456",
      "payload": {
        "metadata": {
          "category": "ML"
        },
        "text": "Another document"
      },
      "score": 0.88
    }
  ],
  "pagination": {
    "has_next": true,
    "limit": 10,
    "offset": 0,
    "total": 100
  },
  "stage_statistics": {
    "stages": {},
    "total_time_ms": 0,
    "credits_used": 0
  },
  "budget": {
    "credits_remaining": 99.5,
    "credits_used": 0.5,
    "time_used_ms": 150
  },
  "error": "Retriever execution failed: Collection not found"
}

Authorizations

​
Authorization
string
header
required

Bearer token authentication using your API key. Format: 'Bearer your_api_key'. To get an API key, create an account at mixpeek.com/start and generate a key in your account settings.

Headers

​
Authorization
string
required

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

Examples:

"Bearer sk_live_abc123def456"

"Bearer sk_test_xyz789"

​
X-Namespace
string
required

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'

Examples:

"ns_abc123def456"

"production"

"my-namespace"

Body

application/json

Request to execute a retriever anonymously (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 NOT tracked - Response includes X-Execution-Mode: anonymous header - execution_metadata.retriever_persisted = False

Examples: Simple anonymous search: { "collection_identifiers": ["col_123"], "input_schema": {"query": {"type": "text", "required": True}}, "stages": [{ "stage_name": "search", "stage_type": "filter", "config": { "stage_id": "hybrid_search", "parameters": { "feature_uri": "mixpeek://text_extractor@v1/embedding", "query_text": "{{inputs.query}}", "top_k": 10 } } }], "inputs": {"query": "machine learning"}, "limit": 25 }

​
collection_identifiers
string[]
required

REQUIRED. Collection identifiers (names or IDs) to query. Can be collection names or IDs. Names are automatically resolved.

Minimum length: 1
Examples:
["my_collection"]
["col_abc123", "products"]
​
input_schema
object
required

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

Examples:
{
  "query": {
    "description": "Search query",
    "required": true,
    "type": "text"
  }
}
{
  "query": { "required": true, "type": "text" },
  "top_k": { "required": false, "type": "integer" }
}
​
stages
StageConfig · object[]
required

REQUIRED. Ordered list of stage configurations. At least one stage is required for execution.

Minimum length: 1
​
inputs
object
required

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

Examples:
{ "query": "machine learning" }
{ "query": "AI trends", "top_k": 50 }
​
budget_limits
object | null

OPTIONAL. Budget limits for execution. User-defined limits for time and credits during execution.

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

Response

Successful Response

Response from retriever execution.

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

​
documents
Documents · object[]

REQUIRED. Final document results after retriever completion. 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. Empty array indicates no documents matched the query criteria. Note: Legacy format may use 'final_results' instead of 'documents'.

Examples:
[
  {
    "document_id": "doc_123",
    "payload": {
      "metadata": { "category": "AI" },
      "text": "Sample content"
    },
    "score": 0.95
  },
  {
    "document_id": "doc_456",
    "payload": {
      "metadata": { "category": "ML" },
      "text": "Another document"
    },
    "score": 0.88
  }
]
​
pagination
object

REQUIRED. Pagination metadata structure. Format varies by pagination method: Offset pagination: {total, limit, offset, has_next, has_previous}, Cursor pagination: {cursor, has_next, page_size}, Keyset pagination: {next_cursor, has_next}. Use this to navigate through result pages.

Examples:
{
  "has_next": true,
  "limit": 10,
  "offset": 0,
  "total": 100
}
{
  "cursor": "abc123",
  "has_next": false,
  "page_size": 20
}
​
stage_statistics
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.

​
budget
object

REQUIRED. Budget usage snapshot for this execution. Contains: credits_used (credits consumed), credits_remaining (remaining budget), time_used_ms (execution time), and budget limits. Use this to track resource consumption and enforce budget limits.

Examples:
{
  "credits_remaining": 99.5,
  "credits_used": 0.5,
  "time_used_ms": 150
}
​
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.

Examples:

"Retriever execution failed: Collection not found"

"Budget exceeded: Maximum credits limit reached"