API reference

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

Request body fields
FieldTypeWhat it is
input_file_idrequiredstring
endpointrequiredstringOne of "/v1/chat/completions", "/v1/embeddings".
completion_windowrequired"24h"
metadataobject

Example

{
  "input_file_id": "string",
  "endpoint": "/v1/chat/completions",
  "completion_window": "24h",
  "metadata": {}
}

Answer 200

The batch, normally validating.

Fields of the 200 answer
FieldTypeWhat it is
idstring
object"batch"
endpointstringOne of "/v1/chat/completions", "/v1/embeddings".
modelstringPresent when every line names the same model.
errorsobject or nullWhy validation failed the batch: {object: list, data: [{code, message, param, line}]}.
input_file_idstring
completion_window"24h"
statusstringOne of "validating", "failed", "in_progress", "finalizing", "completed", "expired", "cancelling", "cancelled".
output_file_idstring or null
error_file_idstring or null
created_atinteger
in_progress_atinteger or null
expires_atinteger
finalizing_atinteger or null
completed_atinteger or null
failed_atinteger or null
expired_atinteger or null
cancelling_atinteger or null
cancelled_atinteger or null
request_countsobject
request_counts.totalinteger
request_counts.completedinteger
request_counts.failedinteger
usageobject
metadataobject 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.

Antimatter