---
title: "List Adhoc Executions"
method: POST
path: "/v1/retrievers/executions/list"
tags: ["Adhoc Retrievers"]
---

# List Adhoc Executions

`POST /v1/retrievers/executions/list`

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

## Query parameters

- `limit` integer, nullable
- `page_size` integer, nullable
- `offset` integer, nullable
- `page` integer, nullable
- `cursor` string, nullable
- `next_cursor` string, nullable
- `after` string, nullable
- `include_total` boolean

## Request body

- ListAdhocExecutionsRequest — 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, nullable — Filter by execution status. Common values: 'completed', 'failed'. OPTIONAL - omit to see all statuses.
  - `start_time` unknown
  - `end_time` unknown
  - `count_only` boolean — 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`

Successful Response

- ListAdhocExecutionsResponse — Response from listing ad-hoc retriever executions.
  - `results` AdhocExecutionSummary[] — List of ad-hoc execution summaries.
    - `execution_id` string, required — Unique execution identifier.
    - `execution_mode` string, required — Execution mode ('adhoc').
    - `status` string, required — Execution status ('completed', 'failed', etc.).
    - `timestamp` unknown, required
    - `duration_ms` number, required — Total execution duration in milliseconds.
    - `credits_used` number, required — Credits consumed during execution.
    - `total_processed` integer, required — Total documents processed across all stages.
    - `total_returned` integer, required — Number of documents returned in final results.
    - `cache_hit_rate` number, nullable — Cache hit rate across stages (0.0-1.0).
    - `query_summary` string, nullable — Brief summary of the query inputs.
    - `stages_completed` integer, required — Number of stages completed.
    - `total_stages` integer, required — Total number of stages in the pipeline.
    - `collection_ids` string[] — Collections queried during execution.
  - `total` integer — Total number of ad-hoc executions matching filters.
  - `pagination` unknown, required

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not Found
- `422` — Validation Error
- `500` — Internal Server Error

---

[API](https://skmtc.net/mixpeek/apis/mixpeek-api.md) · [All operations](https://skmtc.net/mixpeek/apis/mixpeek-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/mixpeek/mixpeek-api/versions/220a3b263fda/schema)