curl --request GET \
--url https://openrouter.ai/api/v1/batches/{id} \
--header 'Authorization: Bearer <token>'import requests
url = "https://openrouter.ai/api/v1/batches/{id}"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://openrouter.ai/api/v1/batches/{id}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://openrouter.ai/api/v1/batches/{id}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://openrouter.ai/api/v1/batches/{id}"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://openrouter.ai/api/v1/batches/{id}")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://openrouter.ai/api/v1/batches/{id}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"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": 401,
"message": "No auth credentials found."
}
}{
"completion_window": "24h",
"created_at": 123,
"endpoint": "<string>",
"error": {
"code": 123,
"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": null,
"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": 404,
"message": "Batch not found."
}
}{
"error": {
"code": 410,
"message": "Batch results have expired. OpenRouter deletes batch results 30 days after the batch is created."
}
}{
"error": {
"code": 429,
"message": "Rate limit exceeded."
}
}{
"error": {
"code": 500,
"message": "Internal server error."
}
}{
"error": {
"code": 502,
"message": "Upstream batch-api is unavailable."
}
}Get a batch
Returns a batch with its status and request counts. Batches in a terminal status include results. Failed batches report the reason in error.message. See the Batch API Quickstart.
curl --request GET \
--url https://openrouter.ai/api/v1/batches/{id} \
--header 'Authorization: Bearer <token>'import requests
url = "https://openrouter.ai/api/v1/batches/{id}"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://openrouter.ai/api/v1/batches/{id}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://openrouter.ai/api/v1/batches/{id}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://openrouter.ai/api/v1/batches/{id}"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://openrouter.ai/api/v1/batches/{id}")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://openrouter.ai/api/v1/batches/{id}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"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": 401,
"message": "No auth credentials found."
}
}{
"completion_window": "24h",
"created_at": 123,
"endpoint": "<string>",
"error": {
"code": 123,
"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": null,
"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": 404,
"message": "Batch not found."
}
}{
"error": {
"code": 410,
"message": "Batch results have expired. OpenRouter deletes batch results 30 days after the batch is created."
}
}{
"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
Path Parameters
The batch job id returned from submit.
1"batch_abc123"
Response
The current batch job status.
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?