Skip to main content
POST
/
v1
/
retrievers
/
{retriever_id}
/
explain
Explain Retriever Execution Plan (Like MongoDB Explain)
curl --request POST \
  --url https://api.mixpeek.com/v1/retrievers/{retriever_id}/explain \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --header 'X-Namespace: <x-namespace>' \
  --data '{
  "inputs": {}
}'
{
  "retriever_id": "<string>",
  "retriever_name": "<string>",
  "estimated_cost": {},
  "total_estimated_stages": 1,
  "execution_plan": [
    {
      "stage_index": 1,
      "stage_name": "<string>",
      "stage_type": "<string>",
      "estimated_input": 1,
      "estimated_output": 1,
      "estimated_efficiency": 1,
      "estimated_cost_credits": 1,
      "estimated_duration_ms": 1,
      "cache_likely": true,
      "optimization_notes": [
        "<string>"
      ],
      "warnings": [
        "<string>"
      ]
    }
  ],
  "optimization_suggestions": [
    {}
  ],
  "bottleneck_stages": [
    "<string>"
  ],
  "optimization_level": "mvp",
  "optimization_applied": false,
  "optimization_details": {
    "decisions": [
      {
        "applied": true,
        "reason": "Moved attribute_filter before feature_filter",
        "rule_type": "push_down_filters",
        "stages_after": 5,
        "stages_before": 5
      },
      {
        "applied": true,
        "reason": "Merged group_by into feature_filter for database-level grouping",
        "rule_type": "group_by_push_down",
        "stages_after": 3,
        "stages_before": 5
      }
    ],
    "optimization_time_ms": 8.2,
    "optimized_stage_count": 3,
    "original_stage_count": 5,
    "stage_reduction_pct": 40
  }
}

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.

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

Path Parameters

​
retriever_id
string
required

Retriever ID or name to explain. The explain plan will be generated for the OPTIMIZED version of this retriever.

Body

application/json

Optional hypothetical inputs to tailor estimation. Use this to see how the plan changes with different input parameters (e.g., different top_k values, different query types).

​
inputs
Inputs · object

Hypothetical inputs used to tailor estimation. These are used to estimate stage behavior and costs. Example: {'query': 'test', 'top_k': 100}

Response

Execution plan with cost estimates, optimization details, and performance insights. Shows the OPTIMIZED pipeline (after automatic transformations). Use optimization_details to understand what changed from your original pipeline.

Explain plan response for a retriever.

​
retriever_id
string
required

Retriever identifier

​
retriever_name
string
required

Retriever name

​
estimated_cost
Estimated Cost · object
required

Estimated cost breakdown (credits/time)

​
total_estimated_stages
integer
required

Total stages considered

Required range: x >= 0
​
execution_plan
ExplainStagePlan · object[]

Ordered stage plan

​
optimization_suggestions
Optimization Suggestions · object[]

Potential optimizations

​
bottleneck_stages
string[]

Stages expected to dominate cost

​
optimization_level
string
default:mvp

Optimizer level applied (e.g., none/mvp/advanced)

​
optimization_applied
boolean
default:false

Whether automatic pipeline optimizations were applied to this explain plan. The execution_plan shows the OPTIMIZED stages (after transformations), not the original user-defined stages. When true, see optimization_details to understand what changed and why.

​
optimization_details
Optimization Details · object

Detailed breakdown of optimizations applied to the pipeline. Only present when optimization_applied=true. Contains: - original_stage_count: Your original stage count - optimized_stage_count: Stages after optimization - optimization_time_ms: Time spent on optimization (<100ms) - decisions: Array of optimization decisions with rule_type, applied, reason - stage_reduction_pct: Percentage reduction in stages Each decision shows which rule fired, whether it applied, and the reason. Use this to understand how your pipeline was transformed for optimal performance.

Example:
{
  "decisions": [
    {
      "applied": true,
      "reason": "Moved attribute_filter before feature_filter",
      "rule_type": "push_down_filters",
      "stages_after": 5,
      "stages_before": 5
    },
    {
      "applied": true,
      "reason": "Merged group_by into feature_filter for database-level grouping",
      "rule_type": "group_by_push_down",
      "stages_after": 3,
      "stages_before": 5
    }
  ],
  "optimization_time_ms": 8.2,
  "optimized_stage_count": 3,
  "original_stage_count": 5,
  "stage_reduction_pct": 40
}