---
title: "Batch Execute Retriever"
method: POST
path: "/v1/retrievers/{retriever_id}/execute/batch"
tags: ["Retrievers"]
---

# Batch Execute Retriever

`POST /v1/retrievers/{retriever_id}/execute/batch`

Execute a retriever against multiple queries in a single request. The retriever is fetched and optimized once, then executed concurrently against each query with bounded parallelism.

**Use case:** IP safety / copyright clearance — scan 20 media files against face, logo, or audio retrievers in one call instead of 60 sequential SSE requests.

**Limits:** 1-50 queries per batch, 1-20 concurrency.

Returns results keyed by query index with per-query documents and errors.

## Path parameters

- `retriever_id` string, required — Retriever ID or name.

## Query parameters

- `return_presigned_urls` boolean — Generate presigned URLs for S3-backed blobs and url-shaped fields. Also accepted as a body field — if either source is true, presigning is enabled.
- `return_vectors` boolean — Include vector embeddings in result documents. Also accepted as a body field — if either source is true, vectors are returned.

## Request body

- ExecuteBatchRequest — Request to execute a retriever against multiple queries in a single call. The retriever is fetched and optimized once, then executed concurrently against each query. Much more efficient than calling /execute N times when scanning multiple assets against the same retriever. Typical use case: IP safety / copyright clearance — check 20 media files against face, logo, or audio retrievers in one request.
  - `queries` BatchQueryItem[], required — List of queries to execute (1-50). Each gets the same retriever pipeline.
    - `inputs` object, required — Runtime inputs for this query (e.g., {'query': 'https://example.com/img.jpg'})
    - `filters` object, nullable — Optional per-query filters.
  - `settings` object, nullable — Shared settings applied to every query. Supports 'limit' (max results per query, default 10) and 'max_chunks' (for content-mode preprocessing).
  - `concurrency` integer — Max concurrent executions (1-20). Higher = faster but more resource usage.
  - `return_presigned_urls` boolean — Generate presigned URLs for S3-backed blobs and url-shaped fields. Also accepted as a query param — if either source is true, presigning is enabled.
  - `return_vectors` boolean — Include vector embeddings in result documents. Also accepted as a query param — if either source is true, vectors are returned.
  - `stream` boolean — Stream results via Server-Sent Events. Each query result is emitted as it completes, with keepalive pings every 15s to prevent proxy timeouts.

## Response `200`

Successful Response

- unknown

## 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/revisions/6e8256aacbc5/schema)