Skip to main content
GET
/
v1
/
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: Bearer <token>' \
  --header 'X-Namespace: <x-namespace>'
{
  "execution_id": "exec_abc123def456",
  "status": "completed",
  "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
    }
  ],
  "pagination": {
    "has_next": true,
    "limit": 10,
    "offset": 0,
    "total": 100
  },
  "stage_statistics": {
    "stages": {},
    "total_time_ms": 0,
    "credits_used": 0
  },
  "budget": {
    "credits_remaining": 99.5,
    "credits_used": 0.5,
    "time_used_ms": 150
  },
  "error": "Retriever execution failed: Collection not found",
  "created_at": "2023-11-07T05:31:56Z",
  "completed_at": "2023-11-07T05:31:56Z",
  "current_stage": "<string>",
  "stages_completed": 0,
  "total_stages": 0
}

Authorizations

​
Authorization
string
header
required

Bearer token authentication using your API key. Format: 'Bearer your_api_key'. To get an API key, create an account at mixpeek.com/start and generate a key in your account settings.

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.

Examples:

"Bearer sk_live_abc123def456"

"Bearer sk_test_xyz789"

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

Examples:

"ns_abc123def456"

"production"

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

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"

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

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
  }
]
​
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
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.

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

Examples:
{
  "credits_remaining": 99.5,
  "credits_used": 0.5,
  "time_used_ms": 150
}
​
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.

Examples:

"Retriever execution failed: Collection not found"

"Budget exceeded: Maximum credits limit reached"

​
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