MImixpeek
Retrievers

Get Execution

Changed on

Get execution details and statistics.

get/v1/retrievers/{retriever_id}/executions/{execution_id}

Request

Path parameters

retriever_idstring required

Retriever ID or name.

execution_idstring required

Execution identifier.

Response

Successful Response

retriever_idstring

The retriever that was executed. Use this to link interactions back to the retriever for learned fusion.

execution_idstring 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.

statusstring required

REQUIRED. Execution status indicating current state. Common values: 'completed', 'failed', 'processing', 'pending'. Check this field to determine if execution succeeded or requires retry.

documentsobject[]

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

resultsobject[]

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.

paginationobject

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.

facetsobject[] nullable

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.

budgetobject

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.

cached_atnumber 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.

completenessobject nullable

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.

warningsstring[]

OPTIONAL. Execution warnings that did not prevent results but indicate potential issues — e.g. filtering on unindexed fields. Empty when there are no warnings.

interpretationobject nullable

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.<stage>.metadata.

errorstring 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_appliedboolean

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_summaryobject 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_contextobject 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_atstring date-time

Timestamp when execution began

completed_atstring date-time nullable

Timestamp when execution finished

current_stagestring nullable

Stage currently running when execution in-flight

stages_completedinteger

Number of stages finished so far

total_stagesinteger

Total stages configured

documents_retainedboolean

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.

total_returnedinteger nullable

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_idstring nullable

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.

Example response

{
  "retriever_id": "ret_abc123def456",
  "execution_id": "exec_abc123def456",
  "status": "completed",
  "degraded": [
    {
      "resource": "taxonomy",
      "id": "tax_abc123",
      "reason": "not found in namespace",
      "next_step": "Fix the taxonomy_id on the stage, or create the taxonomy."
    }
  ],
  "limits": [
    {
      "name": "final_top_k",
      "requested": 2000,
      "applied": 500,
      "ceiling": 500
    }
  ],
  "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
    },
    {
      "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
    }
  ],
  "pagination": {
    "has_next": false,
    "limit": 25,
    "method": "cursor",
    "returned": 25,
    "total": 25
  },
  "budget": {
    "credits_used": 0,
    "llm_calls": 0,
    "metering": "metered"
  },
  "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
  }
}

Changes

  • d4b5fad18960Revision changes
    • info

      added the optional property to the response with the status

  • 61a175e8eb9aRevision changes
    • warning

      removed the optional property from the response with the status

    • info

      added the non-success response with the status

    • info

      added the non-success response with the status

    • info

      added the optional property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status