curl --request GET \
--url https://api.mixpeek.com/v1/retrievers/{retriever_id}/executions/{execution_id} \
--header 'Authorization: Bearer <token>' \
--header 'X-Namespace: <api-key>'import requests
url = "https://api.mixpeek.com/v1/retrievers/{retriever_id}/executions/{execution_id}"
headers = {
"Authorization": "Bearer <token>",
"X-Namespace": "<api-key>"
}
response = requests.get(url, headers=headers)
print(response.text)const options = {
method: 'GET',
headers: {Authorization: 'Bearer <token>', 'X-Namespace': '<api-key>'}
};
fetch('https://api.mixpeek.com/v1/retrievers/{retriever_id}/executions/{execution_id}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.mixpeek.com/v1/retrievers/{retriever_id}/executions/{execution_id}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"X-Namespace: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.mixpeek.com/v1/retrievers/{retriever_id}/executions/{execution_id}"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("X-Namespace", "<api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.mixpeek.com/v1/retrievers/{retriever_id}/executions/{execution_id}")
.header("Authorization", "Bearer <token>")
.header("X-Namespace", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.mixpeek.com/v1/retrievers/{retriever_id}/executions/{execution_id}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
request["X-Namespace"] = '<api-key>'
response = http.request(request)
puts response.read_body{
"execution_id": "exec_abc123def456",
"status": "completed",
"retriever_id": "ret_abc123def456",
"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
}
],
"results": [
{}
],
"pagination": {
"has_next": false,
"limit": 25,
"method": "cursor",
"returned": 25,
"total": 25
},
"stage_statistics": {
"stages": {},
"total_time_ms": 0,
"credits_used": 0,
"server_service_ms": 1
},
"facets": [
{}
],
"budget": {
"credits_remaining": 99.5,
"credits_used": 0.5,
"time_used_ms": 150
},
"cached_at": 123,
"warnings": [
"<string>"
],
"interpretation": {},
"error": "Retriever execution failed: Collection not found",
"optimization_applied": true,
"optimization_summary": {
"optimization_time_ms": 8.2,
"optimized_stage_count": 3,
"original_stage_count": 5,
"rules_applied": [
"push_down_filters",
"group_by_push_down"
],
"stage_reduction_pct": 40
},
"learned_fusion_context": {},
"created_at": "2023-11-07T05:31:56Z",
"completed_at": "2023-11-07T05:31:56Z",
"current_stage": "<string>",
"stages_completed": 0,
"total_stages": 0
}{
"error": {
"details": {
"id": "ns_123",
"resource": "namespace"
},
"message": "Namespace not found",
"type": "NotFoundError"
},
"status": 404,
"success": false
}{
"error": {
"details": {
"id": "ns_123",
"resource": "namespace"
},
"message": "Namespace not found",
"type": "NotFoundError"
},
"status": 404,
"success": false
}{
"error": {
"details": {
"id": "ns_123",
"resource": "namespace"
},
"message": "Namespace not found",
"type": "NotFoundError"
},
"status": 404,
"success": false
}{
"error": {
"details": {
"id": "ns_123",
"resource": "namespace"
},
"message": "Namespace not found",
"type": "NotFoundError"
},
"status": 404,
"success": false
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>",
"input": "<unknown>",
"ctx": {}
}
]
}{
"error": {
"details": {
"id": "ns_123",
"resource": "namespace"
},
"message": "Namespace not found",
"type": "NotFoundError"
},
"status": 404,
"success": false
}Get Execution
Get execution details and statistics.
curl --request GET \
--url https://api.mixpeek.com/v1/retrievers/{retriever_id}/executions/{execution_id} \
--header 'Authorization: Bearer <token>' \
--header 'X-Namespace: <api-key>'import requests
url = "https://api.mixpeek.com/v1/retrievers/{retriever_id}/executions/{execution_id}"
headers = {
"Authorization": "Bearer <token>",
"X-Namespace": "<api-key>"
}
response = requests.get(url, headers=headers)
print(response.text)const options = {
method: 'GET',
headers: {Authorization: 'Bearer <token>', 'X-Namespace': '<api-key>'}
};
fetch('https://api.mixpeek.com/v1/retrievers/{retriever_id}/executions/{execution_id}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.mixpeek.com/v1/retrievers/{retriever_id}/executions/{execution_id}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"X-Namespace: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.mixpeek.com/v1/retrievers/{retriever_id}/executions/{execution_id}"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("X-Namespace", "<api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.mixpeek.com/v1/retrievers/{retriever_id}/executions/{execution_id}")
.header("Authorization", "Bearer <token>")
.header("X-Namespace", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.mixpeek.com/v1/retrievers/{retriever_id}/executions/{execution_id}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
request["X-Namespace"] = '<api-key>'
response = http.request(request)
puts response.read_body{
"execution_id": "exec_abc123def456",
"status": "completed",
"retriever_id": "ret_abc123def456",
"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
}
],
"results": [
{}
],
"pagination": {
"has_next": false,
"limit": 25,
"method": "cursor",
"returned": 25,
"total": 25
},
"stage_statistics": {
"stages": {},
"total_time_ms": 0,
"credits_used": 0,
"server_service_ms": 1
},
"facets": [
{}
],
"budget": {
"credits_remaining": 99.5,
"credits_used": 0.5,
"time_used_ms": 150
},
"cached_at": 123,
"warnings": [
"<string>"
],
"interpretation": {},
"error": "Retriever execution failed: Collection not found",
"optimization_applied": true,
"optimization_summary": {
"optimization_time_ms": 8.2,
"optimized_stage_count": 3,
"original_stage_count": 5,
"rules_applied": [
"push_down_filters",
"group_by_push_down"
],
"stage_reduction_pct": 40
},
"learned_fusion_context": {},
"created_at": "2023-11-07T05:31:56Z",
"completed_at": "2023-11-07T05:31:56Z",
"current_stage": "<string>",
"stages_completed": 0,
"total_stages": 0
}{
"error": {
"details": {
"id": "ns_123",
"resource": "namespace"
},
"message": "Namespace not found",
"type": "NotFoundError"
},
"status": 404,
"success": false
}{
"error": {
"details": {
"id": "ns_123",
"resource": "namespace"
},
"message": "Namespace not found",
"type": "NotFoundError"
},
"status": 404,
"success": false
}{
"error": {
"details": {
"id": "ns_123",
"resource": "namespace"
},
"message": "Namespace not found",
"type": "NotFoundError"
},
"status": 404,
"success": false
}{
"error": {
"details": {
"id": "ns_123",
"resource": "namespace"
},
"message": "Namespace not found",
"type": "NotFoundError"
},
"status": 404,
"success": false
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>",
"input": "<unknown>",
"ctx": {}
}
]
}{
"error": {
"details": {
"id": "ns_123",
"resource": "namespace"
},
"message": "Namespace not found",
"type": "NotFoundError"
},
"status": 404,
"success": false
}Authorizations
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 header returns 403; an invalid or revoked key returns 401.
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.
Path Parameters
Retriever ID or name.
Execution identifier.
Response
Successful Response
Alias wrapper for execution detail documentation.
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.
"exec_abc123def456"
"exec_xyz789"
REQUIRED. Execution status indicating current state. Common values: 'completed', 'failed', 'processing', 'pending'. Check this field to determine if execution succeeded or requires retry.
"completed"
"failed"
"processing"
The retriever that was executed. Use this to link interactions back to the retriever for learned fusion.
"ret_abc123def456"
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'.
[ { "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 } ]
DEPRECATED alias for documents. Previously a computed field that duplicated documents byte-for-byte in every response (~half the payload). It is no longer populated by default to cut response size; pass ?include_legacy_results=true to restore it during migration. Prefer documents — it is and has always been the canonical field. OMITTED from the response when unpopulated while documents has data (an empty results next to populated documents misled readers into 'no results' — 2026-07-06 and again 2026-07-08). When present it is ALWAYS a JSON array, never null. See FRUSTRATIONS.md 2026-04-02 / 2026-06-29 / 2026-06-30.
REQUIRED. Pagination metadata structure. Format varies by pagination method: Offset: {method, page_number, page_size, returned, total, has_next}, Cursor: {method, limit, returned, total, cursor, has_next}, Scroll: {method, scroll_id, limit, returned, total, has_next}, Keyset: {method, limit, returned, total, after}. Every method reports 'total', the number of documents the pipeline computed for this execution BEFORE the page slice, so compare total against returned to detect that a page is a subset. Use this to navigate through result pages.
{ "has_next": false, "limit": 25, "method": "cursor", "returned": 25, "total": 25 }
{ "has_next": true, "method": "offset", "page_number": 1, "page_size": 10, "returned": 10, "total": 40 }
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.
Show child attributes
Show child attributes
Facet value-lists + counts computed by the feature_search stage(s), surfaced at the TOP LEVEL for discoverability: each entry is a FacetResult (a facet key plus value/count buckets). The same data also appears per-stage under stage_statistics.stages.<stage>.metadata.facets; this field is the predictable place a facet consumer looks. When more than one stage computes facets, the last stage's facets are surfaced here. None when no facets were requested.
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.
{ "credits_remaining": 99.5, "credits_used": 0.5, "time_used_ms": 150 }
OPTIONAL. Unix timestamp (seconds) when this result was cached. Present only when the full response was served from the retriever-level cache. Compute freshness as: time.time() - cached_at.
OPTIONAL. Execution warnings that did not prevent results but indicate potential issues — e.g. filtering on unindexed fields. Empty when there are no warnings.
OPTIONAL. What the platform UNDERSTOOD from your request, so a correction or relaxation is visible instead of silent. Keys: provided_input_keys (the inputs you sent), inferred_inputs (schema defaults applied because you omitted the field — name: value), ignored_input_keys (inputs nothing in the pipeline consumes; they had no effect), and relaxations (filter conditions removed because the input they reference was not provided — each names the field, the template, and where it sat; the result set is BROADER than the literal filter when this is non-empty). The literal query text is used AS PROVIDED — no spell-correction step exists; semantic search is typo-tolerant by embedding, which this block does not alter. Stage-level rewrites (e.g. query_expand) report their expansions in stage_statistics.stages..metadata.
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.
"Retriever execution failed: Collection not found"
OPTIONAL. Whether automatic pipeline optimizations were applied before execution. Mixpeek automatically optimizes retrieval pipelines for performance by reordering stages, merging operations, and pushing work to the database layer. Optimizations preserve logical equivalence - you get the same results, just faster. When true, see optimization_summary for details about what changed.
true
false
OPTIONAL. Summary of pipeline optimizations applied before execution. Only present when optimization_applied=true. Contains: - original_stage_count: Number of stages in your original pipeline - optimized_stage_count: Number of stages after optimization - optimization_time_ms: Time spent optimizing (typically <100ms) - rules_applied: List of optimization rules that fired - stage_reduction_pct: Percentage reduction in stage count Use this to understand how the optimizer improved your pipeline. See OptimizationRuleType enum for detailed rule descriptions.
{ "optimization_time_ms": 8.2, "optimized_stage_count": 3, "original_stage_count": 5, "rules_applied": ["push_down_filters", "group_by_push_down"], "stage_reduction_pct": 40 }
OPTIONAL. Learned fusion context when the retriever uses learned fusion (auto-tune) for weight optimization. Contains: context_key (resolution level used), sampled_weights (per-feature weight vector), feature_uris (features that were weighted), effective_exploration (Thompson sampling exploration rate), context_level ('personal', 'segment', or 'global'). Only present when learned fusion is active on this retriever.
Timestamp when execution began
Timestamp when execution finished
Stage currently running when execution in-flight
Number of stages finished so far
x >= 0Total stages configured
x >= 0Was this page helpful?

