Skip to main content
POST

Authorizations

Authorization
string
header
required

API key as bearer token in Authorization header

Body

application/json

The batch to create. Each item in requests has a unique custom_id and a body in the request format of the chosen endpoint.

Batch submit request body.

endpoint
enum<string>
required
Available options:
/v1/chat/completions,
/v1/responses,
/v1/messages,
/v1/embeddings,
/v1/audio/speech
model
string
required
Minimum string length: 1
callback_url
string<uri>

HTTPS URL that receives a batch.completed, batch.failed, batch.cancelled or batch.expired webhook event when the batch reaches a terminal status. Must appear before requests in the request body.

completion_window
enum<string>
default:24h
Available options:
24h
input
object

A batch input file or table in your own storage, named in place of requests. Available to allowlisted callers on Google Vertex BYOK endpoints only.

provider
object | null

Batch provider routing preferences. Only provider.only and provider.allow_fallbacks are supported.

Example:
requests
object[]

The batch requests. Send exactly one of requests or input; requests must be the last field in the request body.

Minimum array length: 1

Response

Batch payload durably persisted and queued for asynchronous validation and provider submission (status: "validating").

completion_window
enum<string>
required
Available options:
24h
created_at
integer
required
endpoint
string
required
error
object | null
required
expires_at
integer | null
required

Unix timestamp after which the assigned provider no longer completes unfinished requests. Derived from the provider's documented batch window, so it can exceed created_at plus completion_window (Google Vertex can take up to 96 hours). null when the provider documents no hard expiry.

finalized_at
integer | null
required
id
string
required
model
string
required
object
enum<string>
required
Available options:
batch
provider
string | null
required

Provider OpenRouter assigned to run the batch, using the same name as the provider field of sync responses.

request_counts
object
required
results
object[] | null
required
status
enum<string>
required
Available options:
validating,
in_progress,
finalizing,
completed,
failed,
expired,
cancelling,
cancelled
usage
object | null
required
output
object

The output location of a batch submitted with input, whose results are null. Returned only by GET /batches/{id}, once the batch has ended and the provider reported an output folder or table. Batch lists and responses for a batch with an unpaid charge leave it out.