Get Execution

curl --request GET \
  --url https://api.mixpeek.com/v1/retrievers/{retriever_id}/executions/{execution_id} \
  --header 'Authorization: <authorization>' \
  --header 'X-Namespace: <x-namespace>'

{
  "execution_id": "<string>",
  "status": "<string>",
  "documents": [
    {}
  ],
  "pagination": {},
  "stage_statistics": {
    "stages": {},
    "total_time_ms": 0,
    "credits_used": 0
  },
  "budget": {},
  "error": "Retriever execution failed: Collection not found",
  "optimization_applied": false,
  "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
  },
  "created_at": "2023-11-07T05:31:56Z",
  "completed_at": "2023-11-07T05:31:56Z",
  "current_stage": "<string>",
  "stages_completed": 0,
  "total_stages": 0
}

GET

retrievers

{retriever_id}

executions

{execution_id}

Get Execution

curl --request GET \
  --url https://api.mixpeek.com/v1/retrievers/{retriever_id}/executions/{execution_id} \
  --header 'Authorization: <authorization>' \
  --header 'X-Namespace: <x-namespace>'

{
  "execution_id": "<string>",
  "status": "<string>",
  "documents": [
    {}
  ],
  "pagination": {},
  "stage_statistics": {
    "stages": {},
    "total_time_ms": 0,
    "credits_used": 0
  },
  "budget": {},
  "error": "Retriever execution failed: Collection not found",
  "optimization_applied": false,
  "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
  },
  "created_at": "2023-11-07T05:31:56Z",
  "completed_at": "2023-11-07T05:31:56Z",
  "current_stage": "<string>",
  "stages_completed": 0,
  "total_stages": 0
}

Headers

Authorization

string

required

REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.

X-Namespace

string

required

REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'

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.

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

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

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.

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

stage_statistics.stages

Stages · object

Per-stage statistics keyed by stage instance name (REQUIRED).

Show child attributes

stage_statistics.stages.{key}

StageStatistics · object

Execution metrics for a single stage in a retriever execution run.

Show child attributes

stage_statistics.stages.{key}.input_count

integer

required

Number of documents received by the stage (REQUIRED).

Required range: x >= 0

stage_statistics.stages.{key}.output_count

integer

required

Number of documents emitted by the stage (REQUIRED).

Required range: x >= 0

stage_statistics.stages.{key}.duration_ms

number

required

Wall-clock duration in milliseconds (REQUIRED).

Required range: x >= 0

stage_statistics.stages.{key}.efficiency

number

required

Output/Input ratio. 0 when input_count is 0 (REQUIRED).

Required range: x >= 0

stage_statistics.stages.{key}.cache_hit

boolean | null

Indicates whether the result originated from stage cache (OPTIONAL).

stage_statistics.stages.{key}.error

string | null

Stage-specific error message if execution failed but retriever execution continued (OPTIONAL).

stage_statistics.stages.{key}.llm_calls

integer | null

Number of LLM invocations performed by the stage (OPTIONAL).

Required range: x >= 0

stage_statistics.stages.{key}.tokens_used

integer | null

Total tokens consumed by the stage (OPTIONAL, only for LLM stages).

Required range: x >= 0

stage_statistics.stages.{key}.metadata

Metadata · object

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.

stage_statistics.total_time_ms

number

default:0

Total retriever execution time in milliseconds (REQUIRED).

Required range: x >= 0

stage_statistics.credits_used

number

default:0

Total credits consumed across all stages (OPTIONAL in MVP).

Required range: x >= 0

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.

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.

optimization_summary

Optimization Summary · object

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
}

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

List Executions Explain Retriever Execution Plan (Like MongoDB Explain)

⌘I

Health

Namespaces

Buckets

Feature Extractors

Collections

Retrievers

Taxonomies

Clusters

Analytics

Tasks

Webhooks

Get Execution

Headers

Path Parameters

Response