Get Execution - Mixpeek

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

retriever_id

string

required

Retriever ID or name.

execution_id

string

required

Execution identifier.

Response

Successful Response

Alias wrapper for execution detail documentation.

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.

Examples:

"exec_abc123def456"

"exec_xyz789"

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.

Examples:

"completed"

"failed"

"processing"

retriever_id

string

default:""

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

Example:

"ret_abc123def456"

documents

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

Example:

[
  {
    "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

Results · object[] | null

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. See FRUSTRATIONS.md 2026-04-02 / 2026-06-29.

pagination

Pagination · object

REQUIRED. Pagination metadata structure. Format varies by pagination method: Offset pagination: {total, limit, offset, has_next, has_previous}, Cursor pagination: {cursor, has_next, page_size}, Keyset pagination: {next_cursor, has_next}. Use this to navigate through result pages.

Examples:

{
  "has_next": true,
  "limit": 10,
  "offset": 0,
  "total": 100
}

{
  "cursor": "abc123",
  "has_next": false,
  "page_size": 20
}

stage_statistics

RetrieverExecutionStatistics · object

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

budget

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.

Example:

{
  "credits_remaining": 99.5,
  "credits_used": 0.5,
  "time_used_ms": 150
}

cached_at

number | null

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 | null

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.

Example:

"Retriever execution failed: Collection not found"

optimization_applied

boolean

default:false

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.

Examples:

true

false

optimization_summary

Optimization Summary · object | null

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.

Example:

{
  "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

Learned Fusion Context · object | null

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> | null

Timestamp when execution finished

current_stage

string | null

Stage currently running when execution in-flight

stages_completed

integer

default:0

Number of stages finished so far

Required range: x >= 0

total_stages

integer

default:0

Total stages configured

Required range: x >= 0