--- title: "Get Execution" method: GET path: "/v1/retrievers/{retriever_id}/executions/{execution_id}" tags: ["Retrievers"] --- # Get Execution `GET /v1/retrievers/{retriever_id}/executions/{execution_id}` Get execution details and statistics. ## Path parameters - `retriever_id` string, required — Retriever ID or name. - `execution_id` string, required — Execution identifier. ## Response `200` Successful Response - ExecutionDetail — Alias wrapper for execution detail documentation. - `retriever_id` string — The retriever that was executed. Use this to link interactions back to the retriever for learned fusion. - `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. - `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. - `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'. - `results` object[] — 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. - `pagination` object — 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. - `stage_statistics` RetrieverExecutionStatistics — Aggregated execution statistics for an entire retriever execution run. - `stages` object — Per-stage statistics keyed by stage instance name (REQUIRED). - `total_time_ms` number — Total retriever execution time in milliseconds (REQUIRED). - `credits_used` number — Total credits consumed across all stages (OPTIONAL in MVP). - `server_service_ms` number, nullable — Controller-measured service span in ms (TG-3105): the wall time of the service.execute_retriever call, stamped by the API controller after execution. Partitions request latency beyond the stages: middleware total minus this = pre-body (DI/auth/tenant resolution); this minus the stage sum = service-outside-stages (cache lookup, plan build, serialization). None on cache-hit replays, whose statistics belong to a different execution. - `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. - `cached_at` number, nullable — 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. - `warnings` string[] — OPTIONAL. Execution warnings that did not prevent results but indicate potential issues — e.g. filtering on unindexed fields. Empty when there are no warnings. - `error` string, nullable — 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. - `optimization_applied` boolean — 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. - `optimization_summary` object, nullable — 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. - `learned_fusion_context` object, nullable — 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. - `created_at` string, date-time — Timestamp when execution began - `completed_at` string, date-time, nullable — Timestamp when execution finished - `current_stage` string, nullable — Stage currently running when execution in-flight - `stages_completed` integer — Number of stages finished so far - `total_stages` integer — Total stages configured ## Other responses - `400` — Bad Request - `401` — Unauthorized - `403` — Forbidden - `404` — Not Found - `422` — Validation Error - `500` — Internal Server Error --- [API](https://skmtc.net/mixpeek/apis/mixpeek-api.md) · [All operations](https://skmtc.net/mixpeek/apis/mixpeek-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/mixpeek/mixpeek-api/versions/5d4c905106b4/schema)