---
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`

## Request

- Base URL: `https://api.mixpeek.com`
- URL: `https://api.mixpeek.com/v1/retrievers/{retriever_id}/execute/batch`
- Auth: HTTP bearer and API key in header `X-Namespace`

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-16 queries per batch (a 17th is refused with `limits.max_queries`), 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 and copyright clearance, checking up to 16 media files against face, logo, or audio retrievers in one request.
  - `queries` BatchQueryItem[], required: List of queries to execute (1-16). Each gets the same retriever pipeline. A request over 16 is refused with 422 and error.details.limits.max_queries set to 16; split larger sets into several requests.
    - `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`: Unprocessable Entity
- `429`: Too Many Requests
- `500`: Internal Server Error
- `503`: Service Unavailable

## Changes

- **2026-10-09** `61a175e8eb9a`: 1 warning, 5 info
  - removed the optional property `detail` from the response with the `422` status
  - added the non-success response with the status `429`
  - added the non-success response with the status `503`
  - added the optional property `success` to the response with the `422` status
  - …2 more
- **2026-08-09** `5d4c905106b4`: 1 info
  - the endpoint scheme security `BearerAuth AND NamespaceHeader` was added to the API

[Operation history](https://skmtc.dev/mixpeek/apis/mixpeek-api/changes/v1/retrievers/:retriever_id/execute/batch/post.md)

---

[API](https://skmtc.dev/mixpeek/apis/mixpeek-api.md) - [All operations](https://skmtc.dev/mixpeek/apis/mixpeek-api/llms.txt) - [OpenAPI document](https://skmtc.dev/mixpeek/apis/mixpeek-api/revisions/790bc16455f6?raw)