API reference · API
Create a batch (OpenAI wire format)
POST/v1/batchesAPI key
Every line runs later through the same dispatch as a live request by the key's owner: the key's policy and scopes, organization budgets, a credit hold and its settlement, metering and the fallback chain all apply, and the batch id is each line's x-antimatter-session label. ANTIMATTER_BATCH_DISCOUNT_BPS (0 unless the operator sets it) is taken off the markup on what each line settles at, never off the upstream's price and never off its hold. A batch whose prompts alone the account cannot pay for is refused with 402 before anything runs. A pass starts as soon as the batch is created; retrieving an unfinished batch and the hourly cron move it on. After 24 hours what has not run expires and what finished is kept. With native batches on (ANTIMATTER_BATCH_NATIVE, the operator's switch), a chat batch whose every line names one OpenAI model, or one Anthropic model, served on the house key is sent whole to that maker's own batch API: each line is held at half its live worst case and charged its usage at the maker's batch price (half its standard card) with the margin on; a line the maker did not run is charged nothing. Mixed batches, organization batches and keys with per request rules (budgets, request counts, strict JSON, output ceilings) run line by line as above.
Request body
application/json, required
| Field | Type | What it is |
|---|---|---|
| input_file_idrequired | string | |
| endpointrequired | string | One of "/v1/chat/completions", "/v1/embeddings". |
| completion_windowrequired | "24h" | |
| metadata | object |
Example
{
"input_file_id": "string",
"endpoint": "/v1/chat/completions",
"completion_window": "24h",
"metadata": {}
}Answer 200
The batch, normally validating.
| Field | Type | What it is |
|---|---|---|
| id | string | |
| object | "batch" | |
| endpoint | string | One of "/v1/chat/completions", "/v1/embeddings". |
| model | string | Present when every line names the same model. |
| errors | object or null | Why validation failed the batch: {object: list, data: [{code, message, param, line}]}. |
| input_file_id | string | |
| completion_window | "24h" | |
| status | string | One of "validating", "failed", "in_progress", "finalizing", "completed", "expired", "cancelling", "cancelled". |
| output_file_id | string or null | |
| error_file_id | string or null | |
| created_at | integer | |
| in_progress_at | integer or null | |
| expires_at | integer | |
| finalizing_at | integer or null | |
| completed_at | integer or null | |
| failed_at | integer or null | |
| expired_at | integer or null | |
| cancelling_at | integer or null | |
| cancelled_at | integer or null | |
| request_counts | object | |
| request_counts. | integer | |
| request_counts. | integer | |
| request_counts. | integer | |
| usage | object | |
| metadata | object or null |
Errors
- 400OpenAI shaped error.
- 401OpenAI shaped error.
- 402OpenAI shaped error.
- 403OpenAI shaped error.
- 404OpenAI shaped error.
- 429OpenAI shaped error.
Every error answers in one shape, with its type, code and the field it names. The whole list is in the docs' Errors section.