# Message Batches Run bulk Messages API work asynchronously at half the token cost. Anthropic-compatible. Message Batches run large sets of [Messages API](https://docs.privatemind.com/messages-api.html) requests asynchronously at **50% of the normal token rate**, in exchange for latency. They share limits and pricing with the OpenAI-format [Batch API](https://docs.privatemind.com/batch.html). The API follows Anthropic's Message Batches API, so the official Anthropic clients work unchanged. ## The flow 1. Create a batch with `POST /v1/messages/batches`, carrying every request inline. 2. Poll it with `GET /v1/messages/batches/{id}` until `processing_status` is `ended`. 3. Stream the results from `GET /v1/messages/batches/{id}/results`. There is no input file to upload: the requests are the body of the create call. PrivateMind stores them as an input file named `msgbatch_….jsonl` with `purpose: batch`. The file appears in your [file list](https://docs.privatemind.com/files.html), can't be deleted through the Files API, and is removed with the batch. A batch created with an org application key is shared with the org, unless a request references a private file. One created with any other key is private to that user, and so is its input file. See [who can see a file](https://docs.privatemind.com/files.html#who-can-see-a-file). ## Create a batch **cURL** ```bash curl -s "https://api.privatemind.com/v1/messages/batches" \ -H "x-api-key: $PMIND_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "Content-Type: application/json" \ -d '{ "requests": [ {"custom_id": "req-1", "params": {"model": "", "max_tokens": 1024, "messages": [{"role": "user", "content": "Summarise: ..."}]}}, {"custom_id": "req-2", "params": {"model": "", "max_tokens": 1024, "messages": [{"role": "user", "content": "Translate to French: ..."}]}} ] }' ``` **Python** ```python import anthropic client = anthropic.Anthropic(base_url="https://api.privatemind.com", api_key=PMIND_KEY) batch = client.messages.batches.create(requests=[ {"custom_id": "req-1", "params": {"model": "", "max_tokens": 1024, "messages": [{"role": "user", "content": "Summarise: ..."}]}}, {"custom_id": "req-2", "params": {"model": "", "max_tokens": 1024, "messages": [{"role": "user", "content": "Translate to French: ..."}]}}, ]) print(batch.id, batch.processing_status) # msgbatch_... in_progress ``` - **`custom_id`** (required): 1 to 64 letters, digits, `_` or `-`, unique within the batch. Results are matched by it, not by order. - **`params`** (required): a normal [`/v1/messages`](https://docs.privatemind.com/messages-api.html) request. `max_tokens` is required and `stream` is ignored. Thinking, tools, images and `file` sources all work. Every request is checked when you create the batch. One invalid request rejects the whole batch, and nothing is created. The `400` names the request, for example `requests.3 (req-4): max_tokens: Field required`. A model without batch turned on in your org also rejects the batch, with a `400` such as `requests.0: body.model is not batch-eligible on this cluster`. A batch that would take your org over its storage quota gets `413`. ## The batch object ```json { "id": "msgbatch_abc123", "type": "message_batch", "processing_status": "in_progress", "request_counts": { "processing": 2, "succeeded": 0, "errored": 0, "canceled": 0, "expired": 0 }, "created_at": "2026-09-30T02:04:32Z", "expires_at": "2026-10-01T02:04:32Z", "ended_at": null, "cancel_initiated_at": null, "archived_at": null, "results_url": null } ``` `processing_status` is `in_progress`, then `canceling` if you cancel with requests still running, then `ended`. Once it is `ended`, `ended_at` and `results_url` are set. `request_counts` always adds up to the number of requests and updates as they finish, so you can track progress. ## Check status **cURL** ```bash curl -s "https://api.privatemind.com/v1/messages/batches/msgbatch_abc123" \ -H "x-api-key: $PMIND_KEY" -H "anthropic-version: 2023-06-01" ``` **Python** ```python import time while batch.processing_status != "ended": time.sleep(30) batch = client.messages.batches.retrieve(batch.id) print(batch.request_counts) ``` There is no push notification, so poll at a modest interval. ## Results Once the batch has ended, `GET /v1/messages/batches/{id}/results` streams JSONL with one line per request. Lines can come in any order, so match them on `custom_id`. Asking earlier returns `409`, and the Python SDK's `results()` raises an error without sending the request, because it checks `results_url` first. **Python** ```python for line in client.messages.batches.results(batch.id): if line.result.type == "succeeded": print(line.custom_id, [b.text for b in line.result.message.content if b.type == "text"]) else: print(line.custom_id, line.result.type) ``` **cURL** ```bash curl -s "https://api.privatemind.com/v1/messages/batches/msgbatch_abc123/results" \ -H "x-api-key: $PMIND_KEY" -H "anthropic-version: 2023-06-01" ``` Each line has your `custom_id` and a `result` of one of four types: ```json {"custom_id": "req-1", "result": {"type": "succeeded", "message": {"id": "msg_...", "type": "message", "role": "assistant", "content": [ ... ], "stop_reason": "end_turn", "usage": { ... }}}} {"custom_id": "req-2", "result": {"type": "errored", "error": {"type": "error", "error": {"type": "invalid_request_error", "message": "..."}}}} {"custom_id": "req-3", "result": {"type": "canceled"}} {"custom_id": "req-4", "result": {"type": "expired"}} ``` - **`succeeded`**: `message` is exactly what `/v1/messages` would have returned. - **`errored`**: `error` uses the same types as the [error table](https://docs.privatemind.com/errors.html#messages-api), such as `invalid_request_error` or `billing_error`. - **`canceled`**: you cancelled the batch before this request started. - **`expired`**: the 24-hour window ended before this request ran. ## Cancel a batch ```bash curl -s -X POST "https://api.privatemind.com/v1/messages/batches/msgbatch_abc123/cancel" \ -H "x-api-key: $PMIND_KEY" -H "anthropic-version: 2023-06-01" ``` Requests that have not started are cancelled. Requests already running finish and are billed, so the batch may stay `canceling` briefly before it ends. Cancelling an ended batch returns it unchanged. ## List batches ```python for b in client.messages.batches.list(limit=20): print(b.id, b.processing_status) ``` `GET /v1/messages/batches` lists the message batches you can see, newest first. Page with `limit` (1 to 1000, default 20) and `after_id` or `before_id`. The SDK pages for you. Batches from the OpenAI-format [Batch API](https://docs.privatemind.com/batch.html) are not in this list. ## Delete a batch ```bash curl -s -X DELETE "https://api.privatemind.com/v1/messages/batches/msgbatch_abc123" \ -H "x-api-key: $PMIND_KEY" -H "anthropic-version: 2023-06-01" ``` Only an ended batch can be deleted. Deleting a running one returns `409`, so cancel it first. Deleting removes the batch and its results at once. Usage already recorded for it stays in [usage](https://docs.privatemind.com/usage.html). ## Limits and retention - **Requests per batch**: up to 10,000. - **Request body**: up to 64 MB for the create call. - **Completion window**: 24 hours from creation. Requests not run by then expire. - **Scheduling**: batch work shares capacity with live traffic and slows it by no more than a small margin. See [When batch work runs](https://docs.privatemind.com/batch.html#when-batch-work-runs). - **Pricing**: 50% of the normal per-token rate, applied to work that actually ran. - **Rate of creation**: each org can create 20 batches per hour and have 50,000 requests queued or running. Both caps are shared with the [Batch API](https://docs.privatemind.com/batch.html). - **Retention**: results are kept for **29 days** after the batch ends. Then they are deleted, `archived_at` is set and `results_url` goes back to `null`. Delete sooner if you do not need them. - **Storage**: the batch's internal input file counts toward your org's storage quota until the batch is deleted or retention removes it. > [!NOTE] > Batch requests and results hold your content on our servers, so Message Batches are not eligible for zero-data-retention (ZDR) arrangements. ## Where next - [Messages API](https://docs.privatemind.com/messages-api.html) for the request shape each batch request carries. - [Batch API](https://docs.privatemind.com/batch.html) for the OpenAI-shaped equivalent. - [Budgets and limits](https://docs.privatemind.com/budgets-and-limits.html) for how the 50% batch rate counts against your budget. - [Errors](https://docs.privatemind.com/errors.html#messages-api) for status codes and error types.