List Adhoc Executions

List execution history for ad-hoc retrievers.

Returns execution history for all ad-hoc retriever executions in the namespace, sorted by timestamp descending (most recent first).

Use Cases:

• Track ad-hoc retriever usage across the namespace
• Debug ad-hoc retriever executions
• Analyze query patterns from ad-hoc searches
• Monitor performance of ad-hoc executions

Filtering:

• Filter by status (completed, failed, etc.)
• Filter by time range (start_time, end_time)

Pagination:

• Supports offset-based pagination via query parameters
• Default limit: 20, max limit: 100
• Use ?page_size=X&page_number=Y for pagination

POST /v1/retrievers/executions/list

List Adhoc Executions

cURL

curl --request POST \
  --url https://api.mixpeek.com/v1/retrievers/executions/list \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Namespace: <api-key>' \
  --data '
{
  "status": "completed",
  "start_time": "<unknown>",
  "end_time": "<unknown>",
  "count_only": false
}
'

200

{
  "pagination": "<unknown>",
  "results": [
    {
      "execution_id": "<string>",
      "execution_mode": "<string>",
      "status": "<string>",
      "timestamp": "<unknown>",
      "duration_ms": 1,
      "credits_used": 1,
      "total_processed": 1,
      "total_returned": 1,
      "stages_completed": 1,
      "total_stages": 1,
      "cache_hit_rate": 0.5,
      "query_summary": "<string>",
      "collection_ids": [
        "<string>"
      ]
    }
  ],
  "total": 0
}

Authorizations

Authorization · string · header · required

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 header returns 403; an invalid or revoked key returns 401.

X-Namespace · string · header · required

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.

Query Parameters

limit · integer | null

Required range: 1 <= x <= 1000

page_size · integer | null

Required range: 1 <= x <= 1000

offset · integer | null

Required range: 0 <= x <= 10000

page · integer | null

Required range: x >= 1

cursor · string | null

next_cursor · string | null

after · string | null

include_total · boolean · default: false

Body

application/json

Request to list ad-hoc retriever executions with filtering.

Allows filtering by status, time range, and searching by query summary. Results are ordered by timestamp descending (most recent first).

status · string | null

Filter by execution status. Common values: 'completed', 'failed'. OPTIONAL - omit to see all statuses.

Example:

"completed"

start_time · any | null

Filter executions after this timestamp (inclusive). OPTIONAL - omit for no start time filter.

end_time · any | null

Filter executions before this timestamp (inclusive). OPTIONAL - omit for no end time filter.

count_only · boolean · default: false

BACKE-3071: when true, return ONLY the total count and skip fetching the execution rows. Use for a badge/total (the Executions-tab count) — it avoids the ORDER BY full-row scan that made a limit:1 count take 15s+.

Response

200

application/json

Successful Response

Response from listing ad-hoc retriever executions.

pagination · any · required

Pagination metadata.

results · AdhocExecutionSummary · object[]

List of ad-hoc execution summaries.

Show child attributes

total · integer · default: 0

Total number of ad-hoc executions matching filters.