curl --request POST \
--url https://openrouter.ai/api/v1/batches \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"endpoint": "/v1/chat/completions",
"model": "openai/gpt-4o",
"requests": [
{
"body": {
"messages": [
{
"content": "Summarize ...",
"role": "user"
}
],
"model": "openai/gpt-4o"
},
"custom_id": "req-0001"
}
]
}
'{
"completion_window": "24h",
"created_at": 123,
"endpoint": "<string>",
"error": {
"message": "<string>"
},
"expires_at": 123,
"finalized_at": 123,
"id": "<string>",
"model": "<string>",
"object": "batch",
"provider": "<string>",
"request_counts": {
"completed": 123,
"failed": 123,
"total": 123
},
"results": [
{
"custom_id": "<string>",
"error": {
"message": "<string>",
"param": "<string>",
"type": "<string>",
"error_type": "rate_limit_exceeded"
},
"id": "<string>",
"response": {
"body": {
"choices": [
{
"finish_reason": "stop",
"index": 123,
"logprobs": {
"content": [
{
"bytes": [
123
],
"logprob": 123,
"token": "<string>",
"top_logprobs": [
{
"bytes": [
123
],
"logprob": 123,
"token": "<string>"
}
]
}
],
"refusal": null
},
"message": {
"content": "<string>",
"refusal": "<string>",
"role": "assistant",
"annotations": [
{
"file": {
"content": [
{
"text": "<string>",
"type": "text"
}
],
"hash": "<string>",
"name": "<string>"
},
"type": "file"
}
],
"images": [
{
"image_url": {
"url": "<string>"
},
"type": "image_url"
}
],
"reasoning": "<string>",
"reasoning_details": [
{
"summary": "The model analyzed the problem by first identifying key constraints, then evaluating possible solutions...",
"type": "reasoning.summary"
}
],
"tool_calls": [
{
"function": {
"arguments": "<string>",
"name": "<string>"
},
"id": "<string>",
"index": 123,
"type": "function"
}
]
},
"native_finish_reason": "<string>"
}
],
"created": 123,
"id": "<string>",
"model": "<string>",
"object": "chat.completion",
"alignment": {
"calls": [
{
"call": 1,
"outcome": "allowed",
"rules": [
{
"applicable": true,
"broken": false,
"probability": 0.04
}
]
}
]
},
"debug": {
"echo_upstream_body": {},
"timings": {
"epoch_ms": 123,
"event": "adapter_request",
"start_ms": 123
}
},
"openrouter_metadata": {
"attempt": 1,
"endpoints": {
"available": [
{
"model": "openai/gpt-4o",
"provider": "OpenAI",
"selected": true
}
],
"total": 1
},
"generation_time": 2016,
"is_byok": false,
"region": "iad",
"requested": "openai/gpt-4o",
"strategy": "direct",
"summary": "available=1, selected=OpenAI"
},
"provider": "<string>",
"safeguard_results": [
{
"status": {
"tool_uses": {
"call_abc": {
"explanation": "[Data Exfiltration]",
"outcome": "flagged",
"type": "evaluated"
},
"call_def": {
"outcome": "not_flagged",
"type": "evaluated"
}
},
"type": "available"
},
"type": "dangerous_tool_use"
}
],
"service_tier": "<string>",
"system_fingerprint": "<string>",
"usage": {
"completion_tokens": 123,
"prompt_tokens": 123,
"total_tokens": 123,
"completion_tokens_details": {
"audio_tokens": 123,
"image_tokens": 123,
"reasoning_tokens": 123
},
"prompt_tokens_details": {
"audio_tokens": 123,
"cache_write_tokens": 123,
"cached_tokens": 123,
"file_tokens": 123,
"video_tokens": 123
},
"server_tool_use": {
"tool_calls_executed": 123,
"tool_calls_requested": 123,
"web_search_requests": 123
},
"server_tool_use_details": {
"tool_calls_executed": 123,
"tool_calls_requested": 123,
"web_search_requests": 123
}
}
},
"request_id": "<string>",
"status_code": 123
}
}
],
"status": "validating",
"usage": {
"completion_tokens": 123,
"prompt_tokens": 123,
"total_tokens": 123,
"cache_creation": {
"ephemeral_1h_input_tokens": 0,
"ephemeral_5m_input_tokens": 100
},
"completion_tokens_details": {
"audio_tokens": 123,
"image_tokens": 123,
"reasoning_tokens": 123
},
"cost": 123,
"cost_details": {
"upstream_inference_completions_cost": 0.0004,
"upstream_inference_cost": null,
"upstream_inference_prompt_cost": 0.0008
},
"is_byok": true,
"iterations": [
{
"cache_creation": null,
"cache_creation_input_tokens": 0,
"cache_read_input_tokens": 0,
"input_tokens": 100,
"output_tokens": 50,
"type": "message"
}
],
"prompt_tokens_details": {
"audio_tokens": 123,
"cache_write_tokens": 123,
"cached_tokens": 123,
"file_tokens": 123,
"video_tokens": 123
},
"server_tool_use": {
"tool_calls_executed": 123,
"tool_calls_requested": 123,
"web_search_requests": 123
},
"service_tier": "<string>",
"speed": "standard"
}
}{
"error": {
"code": 400,
"message": "custom_id is required on requests[0]."
}
}{
"error": {
"code": 401,
"message": "No auth credentials found."
}
}{
"error": {
"code": 402,
"message": "Insufficient balance for this batch."
}
}{
"error": {
"code": 403,
"message": "The selected provider or model is not allowed."
}
}{
"error": {
"code": 404,
"message": "Batch not found."
}
}{
"error": {
"code": 413,
"message": "Batch input exceeds the 200 MB payload limit."
}
}{
"error": {
"code": 422,
"message": "The batch request could not be processed."
}
}{
"error": {
"code": 429,
"message": "Rate limit exceeded."
}
}{
"error": {
"code": 500,
"message": "Internal server error."
}
}{
"error": {
"code": 502,
"message": "Upstream batch-api is unavailable."
}
}Create a batch
Creates a batch of requests that run asynchronously against a single endpoint (/v1/chat/completions, /v1/responses, /v1/messages, /v1/embeddings). Returns 202 with status: "validating". Poll GET /batches/{id} for progress and results. See the Batch API Quickstart.
curl --request POST \
--url https://openrouter.ai/api/v1/batches \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"endpoint": "/v1/chat/completions",
"model": "openai/gpt-4o",
"requests": [
{
"body": {
"messages": [
{
"content": "Summarize ...",
"role": "user"
}
],
"model": "openai/gpt-4o"
},
"custom_id": "req-0001"
}
]
}
'{
"completion_window": "24h",
"created_at": 123,
"endpoint": "<string>",
"error": {
"message": "<string>"
},
"expires_at": 123,
"finalized_at": 123,
"id": "<string>",
"model": "<string>",
"object": "batch",
"provider": "<string>",
"request_counts": {
"completed": 123,
"failed": 123,
"total": 123
},
"results": [
{
"custom_id": "<string>",
"error": {
"message": "<string>",
"param": "<string>",
"type": "<string>",
"error_type": "rate_limit_exceeded"
},
"id": "<string>",
"response": {
"body": {
"choices": [
{
"finish_reason": "stop",
"index": 123,
"logprobs": {
"content": [
{
"bytes": [
123
],
"logprob": 123,
"token": "<string>",
"top_logprobs": [
{
"bytes": [
123
],
"logprob": 123,
"token": "<string>"
}
]
}
],
"refusal": null
},
"message": {
"content": "<string>",
"refusal": "<string>",
"role": "assistant",
"annotations": [
{
"file": {
"content": [
{
"text": "<string>",
"type": "text"
}
],
"hash": "<string>",
"name": "<string>"
},
"type": "file"
}
],
"images": [
{
"image_url": {
"url": "<string>"
},
"type": "image_url"
}
],
"reasoning": "<string>",
"reasoning_details": [
{
"summary": "The model analyzed the problem by first identifying key constraints, then evaluating possible solutions...",
"type": "reasoning.summary"
}
],
"tool_calls": [
{
"function": {
"arguments": "<string>",
"name": "<string>"
},
"id": "<string>",
"index": 123,
"type": "function"
}
]
},
"native_finish_reason": "<string>"
}
],
"created": 123,
"id": "<string>",
"model": "<string>",
"object": "chat.completion",
"alignment": {
"calls": [
{
"call": 1,
"outcome": "allowed",
"rules": [
{
"applicable": true,
"broken": false,
"probability": 0.04
}
]
}
]
},
"debug": {
"echo_upstream_body": {},
"timings": {
"epoch_ms": 123,
"event": "adapter_request",
"start_ms": 123
}
},
"openrouter_metadata": {
"attempt": 1,
"endpoints": {
"available": [
{
"model": "openai/gpt-4o",
"provider": "OpenAI",
"selected": true
}
],
"total": 1
},
"generation_time": 2016,
"is_byok": false,
"region": "iad",
"requested": "openai/gpt-4o",
"strategy": "direct",
"summary": "available=1, selected=OpenAI"
},
"provider": "<string>",
"safeguard_results": [
{
"status": {
"tool_uses": {
"call_abc": {
"explanation": "[Data Exfiltration]",
"outcome": "flagged",
"type": "evaluated"
},
"call_def": {
"outcome": "not_flagged",
"type": "evaluated"
}
},
"type": "available"
},
"type": "dangerous_tool_use"
}
],
"service_tier": "<string>",
"system_fingerprint": "<string>",
"usage": {
"completion_tokens": 123,
"prompt_tokens": 123,
"total_tokens": 123,
"completion_tokens_details": {
"audio_tokens": 123,
"image_tokens": 123,
"reasoning_tokens": 123
},
"prompt_tokens_details": {
"audio_tokens": 123,
"cache_write_tokens": 123,
"cached_tokens": 123,
"file_tokens": 123,
"video_tokens": 123
},
"server_tool_use": {
"tool_calls_executed": 123,
"tool_calls_requested": 123,
"web_search_requests": 123
},
"server_tool_use_details": {
"tool_calls_executed": 123,
"tool_calls_requested": 123,
"web_search_requests": 123
}
}
},
"request_id": "<string>",
"status_code": 123
}
}
],
"status": "validating",
"usage": {
"completion_tokens": 123,
"prompt_tokens": 123,
"total_tokens": 123,
"cache_creation": {
"ephemeral_1h_input_tokens": 0,
"ephemeral_5m_input_tokens": 100
},
"completion_tokens_details": {
"audio_tokens": 123,
"image_tokens": 123,
"reasoning_tokens": 123
},
"cost": 123,
"cost_details": {
"upstream_inference_completions_cost": 0.0004,
"upstream_inference_cost": null,
"upstream_inference_prompt_cost": 0.0008
},
"is_byok": true,
"iterations": [
{
"cache_creation": null,
"cache_creation_input_tokens": 0,
"cache_read_input_tokens": 0,
"input_tokens": 100,
"output_tokens": 50,
"type": "message"
}
],
"prompt_tokens_details": {
"audio_tokens": 123,
"cache_write_tokens": 123,
"cached_tokens": 123,
"file_tokens": 123,
"video_tokens": 123
},
"server_tool_use": {
"tool_calls_executed": 123,
"tool_calls_requested": 123,
"web_search_requests": 123
},
"service_tier": "<string>",
"speed": "standard"
}
}{
"error": {
"code": 400,
"message": "custom_id is required on requests[0]."
}
}{
"error": {
"code": 401,
"message": "No auth credentials found."
}
}{
"error": {
"code": 402,
"message": "Insufficient balance for this batch."
}
}{
"error": {
"code": 403,
"message": "The selected provider or model is not allowed."
}
}{
"error": {
"code": 404,
"message": "Batch not found."
}
}{
"error": {
"code": 413,
"message": "Batch input exceeds the 200 MB payload limit."
}
}{
"error": {
"code": 422,
"message": "The batch request could not be processed."
}
}{
"error": {
"code": 429,
"message": "Rate limit exceeded."
}
}{
"error": {
"code": 500,
"message": "Internal server error."
}
}{
"error": {
"code": 502,
"message": "Upstream batch-api is unavailable."
}
}Authorizations
API key as bearer token in Authorization header
Body
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.
/v1/chat/completions, /v1/responses, /v1/messages, /v1/embeddings 11Show child attributes
Show child attributes
24h Batch provider routing preferences. Only provider.only and provider.allow_fallbacks are supported.
Show child attributes
Show child attributes
{ "only": ["google-vertex"] }
Response
Batch payload durably persisted and queued for asynchronous validation and provider submission (status: "validating").
24h Show child attributes
Show child attributes
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.
batch Provider OpenRouter assigned to run the batch, using the same name as the provider field of sync responses.
Show child attributes
Show child attributes
Show child attributes
Show child attributes
validating, in_progress, finalizing, completed, failed, expired, cancelling, cancelled Show child attributes
Show child attributes
Was this page helpful?