> ## Documentation Index > Fetch the complete documentation index at: https://docs.mixpeek.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Get Execution > Get execution details and statistics. ## OpenAPI ````yaml get /v1/retrievers/{retriever_id}/executions/{execution_id} openapi: 3.1.0 info: title: Mixpeek API description: >- This is the Mixpeek API, providing access to various endpoints for data processing and retrieval. termsOfService: https://mixpeek.com/terms contact: name: Mixpeek Support url: https://mixpeek.com/contact email: info@mixpeek.com version: '0.82' servers: - url: https://api.mixpeek.com description: Production security: - BearerAuth: [] paths: /v1/retrievers/{retriever_id}/executions/{execution_id}: get: tags: - Retrievers summary: Get Execution description: Get execution details and statistics. operationId: get_execution_v1_retrievers__retriever_id__executions__execution_id__get parameters: - name: retriever_id in: path required: true schema: type: string description: Retriever ID or name. title: Retriever Id description: Retriever ID or name. - name: execution_id in: path required: true schema: type: string description: Execution identifier. title: Execution Id description: Execution identifier. responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/ExecutionDetail' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '422': description: Unprocessable Entity content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: Too Many Requests content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '503': description: Service Unavailable content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - BearerAuth: [] NamespaceHeader: [] components: schemas: ExecutionDetail: properties: retriever_id: type: string title: Retriever Id description: >- The retriever that was executed. Use this to link interactions back to the retriever for learned fusion. default: '' examples: - ret_abc123def456 execution_id: type: string title: Execution Id description: >- 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: type: string title: Status description: >- 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 degraded: items: $ref: '#/components/schemas/DegradedEntry' type: array title: Degraded description: >- What this run skipped, one entry per resource, when status is 'degraded': the resource kind, its id, why it was skipped, and what to do about it. Empty on a clean run. A degraded run may return few or no documents; read these before treating an empty result as a real no-match. limits: anyOf: - items: $ref: '#/components/schemas/LimitEntry' type: array - type: 'null' title: Limits description: >- OPTIONAL. Every cap that clamped this request: the setting, the value asked for, the value used, the cap's maximum and the stage that applied it. Absent when nothing was capped. A run that hit a cap can return fewer documents than asked; read this before treating a short result as everything that matched. documents: items: additionalProperties: true type: object type: array title: Documents description: >- REQUIRED. Final document results after retriever completion, and the canonical result key: read `documents`, not `results` (the latter is a deprecated byte-for-byte alias, off unless include_legacy_results=true, and its ABSENCE on a normal response must not be read as zero results). 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. The moment_group reduce stage annotates each document with a `moments` array of merged time ranges; each moment has start_ms, end_ms, duration_ms, score, match_count and document_ids (see the moment-annotated example). 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 - document_id: moment_vid_A_12000 moments: - document_ids: - frame_41 - frame_42 - frame_43 duration_ms: 6500 end_ms: 18500 match_count: 3 score: 0.91 start_ms: 12000 parent_id: vid_A score: 0.91 results: items: additionalProperties: true type: object type: array title: Results description: >- 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. deprecated: true pagination: additionalProperties: true type: object title: Pagination description: >- 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. examples: - 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 stage_statistics: $ref: '#/components/schemas/RetrieverExecutionStatistics' description: >- 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. facets: anyOf: - items: additionalProperties: true type: object type: array - type: 'null' title: Facets description: >- 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..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. budget: additionalProperties: true type: object title: Budget description: >- REQUIRED. This run's usage: credits_used, credits_limit, time_elapsed_ms, time_limit_ms, tokens_used, llm_calls, metering. credits_used is what was charged to this run; a plain text search and a cache hit read 0.0. metering is 'unmetered' where there is no billing path, and credits_used is no price. examples: - credits_used: 0 llm_calls: 0 metering: metered cached_at: anyOf: - type: number - type: 'null' title: Cached At description: >- 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. completeness: anyOf: - additionalProperties: type: string type: object - type: 'null' title: Completeness description: >- Completeness by layer, so the claims never contradict: `embeddings` is complete, complete_after_retry or partial (some query embeddings were dropped); `page` is complete, not_known_complete (a retried stage answered an empty page) or the execution status; `overall` is complete only when both layers are. Filled in when the response is written. warnings: items: type: string type: array title: Warnings description: >- OPTIONAL. Execution warnings that did not prevent results but indicate potential issues — e.g. filtering on unindexed fields. Empty when there are no warnings. interpretation: anyOf: - additionalProperties: true type: object - type: 'null' title: Interpretation description: >- 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. error: anyOf: - type: string - type: 'null' title: Error description: >- 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' optimization_applied: type: boolean title: Optimization Applied description: >- 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. default: false examples: - true - false optimization_summary: anyOf: - additionalProperties: true type: object - type: 'null' title: Optimization Summary description: >- 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. examples: - 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 - optimization_time_ms: 2.1 optimized_stage_count: 3 original_stage_count: 3 rules_applied: [] stage_reduction_pct: 0 learned_fusion_context: anyOf: - additionalProperties: true type: object - type: 'null' title: Learned Fusion Context description: >- 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: type: string format: date-time title: Created At description: Timestamp when execution began completed_at: anyOf: - type: string format: date-time - type: 'null' title: Completed At description: Timestamp when execution finished current_stage: anyOf: - type: string - type: 'null' title: Current Stage description: Stage currently running when execution in-flight stages_completed: type: integer minimum: 0 title: Stages Completed description: Number of stages finished so far default: 0 total_stages: type: integer minimum: 0 title: Total Stages description: Total stages configured default: 0 documents_retained: type: boolean title: Documents Retained description: >- Whether the documents this run returned are stored with it. FALSE means `documents` is empty because nothing was persisted, NOT because the query matched nothing: a stored execution keeps the statistics and not the result rows. Read `total_returned` below for what the run actually returned. This exists because an empty `documents` on a completed run is otherwise indistinguishable from a real empty result, and the same reasoning is already written down one field over, where `documents` says the ABSENCE of `results` must not be read as zero results. default: false total_returned: anyOf: - type: integer - type: 'null' title: Total Returned description: >- Documents this run returned to the caller, as recorded when it ran. Present on a stored read even when `documents` is empty and `documents_retained` is false, which is what lets a caller tell 'returned 3, not retained' from 'matched nothing'. None when the stored record does not carry it. trace_id: anyOf: - type: string - type: 'null' title: Trace Id description: >- Trace identifier recorded when this execution ran. Quote it to Mixpeek support to find the request's trace. Null for executions recorded before trace ids were stored. type: object required: - execution_id - status title: ExecutionDetail description: Alias wrapper for execution detail documentation. ErrorResponse: properties: success: type: boolean title: Success description: Always false for error responses default: false status: type: integer title: Status description: HTTP status code for this error error: $ref: '#/components/schemas/ErrorDetail' description: Error details payload type: object required: - status - error title: ErrorResponse description: Error response model. examples: - error: details: id: ns_123 resource: namespace message: Namespace not found type: NotFoundError status: 404 success: false DegradedEntry: properties: resource: type: string title: Resource description: >- Kind of resource skipped: stage, collection, taxonomy, retriever, namespace. examples: - taxonomy id: anyOf: - type: string - type: 'null' title: Id description: Identifier of the skipped resource, when it has one. examples: - tax_abc123 reason: type: string title: Reason description: Why it was skipped. examples: - not found in namespace next_step: type: string title: Next Step description: What the caller can do about it. examples: - Fix the taxonomy_id on the stage, or create the taxonomy. stage: anyOf: - type: string - type: 'null' title: Stage description: The stage that skipped it, when a stage did. type: object required: - resource - reason - next_step title: DegradedEntry description: |- One resource a response could not include (plan 6.16). The same shape 6.10's degradation contract uses for its stage and arm entries, so a client reads one structure for every kind of skip. LimitEntry: properties: name: type: string title: Name description: The setting that was capped. examples: - final_top_k - pagination_depth requested: type: integer title: Requested description: The value the request asked for. examples: - 2000 applied: type: integer title: Applied description: The value the platform used. examples: - 500 ceiling: type: integer title: Ceiling description: The cap's maximum for this setting. examples: - 500 stage: anyOf: - type: string - type: 'null' title: Stage description: The stage that applied the cap, when a stage did. type: object required: - name - requested - applied - ceiling title: LimitEntry description: >- One cap that clamped a request (plan 6.10's ``limits``). Reported when the platform applied a smaller value than the request asked for, so a short result reads as the cap rather than as a no-match. RetrieverExecutionStatistics: properties: stages: additionalProperties: $ref: '#/components/schemas/StageStatistics' type: object title: Stages description: Per-stage statistics keyed by stage instance name (REQUIRED). total_time_ms: type: number minimum: 0 title: Total Time Ms description: Total retriever execution time in milliseconds (REQUIRED). default: 0 credits_used: type: number minimum: 0 title: Credits Used description: Same value as budget.credits_used on an execute response. default: 0 server_service_ms: anyOf: - type: number minimum: 0 - type: 'null' title: Server Service Ms description: >- Controller-measured service span in ms: 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. type: object title: RetrieverExecutionStatistics description: Aggregated execution statistics for an entire retriever execution run. ErrorDetail: properties: message: type: string title: Message description: Human-readable error message type: type: string title: Type description: Stable error type identifier (machine-readable) code: anyOf: - type: string - type: 'null' title: Code description: >- Fine-grained error code for programmatic handling (e.g., namespace_name_taken, feature_extractor_not_found). Present only when consumers may need to branch on a specific error condition. details: anyOf: - additionalProperties: true type: object - type: 'null' title: Details description: >- Optional structured details to help debugging (validation errors, IDs, etc.) type: object required: - message - type title: ErrorDetail description: Error detail model. StageStatistics: properties: input_count: type: integer minimum: 0 title: Input Count description: Number of documents received by the stage (REQUIRED). output_count: type: integer minimum: 0 title: Output Count description: Number of documents emitted by the stage (REQUIRED). duration_ms: type: number minimum: 0 title: Duration Ms description: Wall-clock duration in milliseconds (REQUIRED). efficiency: type: number minimum: 0 title: Efficiency description: Output/Input ratio. 0 when input_count is 0 (REQUIRED). cache_hit: anyOf: - type: boolean - type: 'null' title: Cache Hit description: >- Deprecated alias for stage_cache_hit, kept for existing callers (OPTIONAL). Despite the name, this describes only THIS stage's own cache, not the retriever-level execute cache reported by cache_hit on the top-level response -- the two fields have shared this name across different response levels and that has misled multiple verification passes. Prefer stage_cache_hit. stage_cache_hit: anyOf: - type: boolean - type: 'null' title: Stage Cache Hit description: >- Indicates whether THIS stage served its result from its own stage cache (OPTIONAL). Distinct from cache_hit on the top-level retriever execution response, which describes a separate, retriever-level execute cache; a stage can report stage_cache_hit=true on a response whose top-level cache_hit is false, and that is not a contradiction. cached_at: anyOf: - type: number - type: 'null' title: Cached At description: >- Unix timestamp when this stage result was cached. Present only on cache hits. error: anyOf: - type: string - type: 'null' title: Error description: >- Stage-specific error message if execution failed but retriever execution continued (OPTIONAL). llm_calls: anyOf: - type: integer minimum: 0 - type: 'null' title: Llm Calls description: Number of LLM invocations performed by the stage (OPTIONAL). tokens_used: anyOf: - type: integer minimum: 0 - type: 'null' title: Tokens Used description: Total tokens consumed by the stage (OPTIONAL, only for LLM stages). metadata: additionalProperties: true type: object title: Metadata description: >- Stage-specific metadata containing additional execution details (OPTIONAL). For example, join stages include: join_strategy, join_type, matched_count, match_rate, etc. LLM stages may include: model_name, temperature, max_tokens, etc. type: object required: - input_count - output_count - duration_ms - efficiency title: StageStatistics description: Execution metrics for a single stage in a retriever execution run. examples: - cache_hit: false duration_ms: 123.4 efficiency: 0.05 input_count: 5000 output_count: 250 stage_cache_hit: false securitySchemes: BearerAuth: type: http scheme: bearer description: >- 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, malformed, unknown, revoked, inactive or expired key returns 401; a key without the permission, scope or plan an operation needs returns 403. NamespaceHeader: type: apiKey in: header name: X-Namespace description: >- 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`. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.