Skip to main content

​
Overview

The Batch API allows you to submit multiple API requests in a single batch for asynchronous processing. Batches offer 50% cost savings and a separate pool of significantly higher rate limits.

​
Create batch

Creates and executes a batch from an uploaded file of requests. 
batch = client.batches.create(
  input_file_id: "file-abc123",
  endpoint: "/v1/responses",
  completion_window: "24h"
)

​
Parameters

​
input_file_id
string
required
The ID of an uploaded file containing requests for the batch. Each line must be a valid JSON object with:
  • custom_id - Your identifier for the request
  • method - HTTP method (currently only POST)
  • url - The endpoint path
  • body - Request parameters
​
endpoint
string
required
The API endpoint for all requests in the batch. Currently supported:
  • /v1/responses - Responses API
  • /v1/embeddings - Embeddings API
​
completion_window
string
required
Time frame for processing. Currently only 24h is supported.
​
metadata
hash
Optional metadata (up to 16 key-value pairs)
​
output_expires_after
object
Expiration policy for output/error files

​
Response

Returns a Batch object:
​
id
string
Unique batch identifier
​
status
string
Current status: validating, failed, in_progress, finalizing, completed, expired, cancelling, or cancelled
​
input_file_id
string
ID of the input file
​
output_file_id
string
ID of the output file (available when completed)
​
error_file_id
string
ID of the error file (if any requests failed)
​
request_counts
object
Request counts by status:

​
Retrieve batch

Retrieves a batch by ID. 
batch = client.batches.retrieve("batch_abc123")
puts batch.status

​
Parameters

​
batch_id
string
required
The ID of the batch to retrieve

​
List batches

Lists your organization’s batches. 
batches = client.batches.list(limit: 10)

batches.data.each do |batch|
  puts "#{batch.id}: #{batch.status}"
end

​
Parameters

​
limit
integer
Number of objects to return (1-100, default: 20)
​
after
string
Cursor for pagination

​
Cancel batch

Cancels an in-progress batch. The batch will move to cancelling status for up to 10 minutes before becoming cancelled. 
batch = client.batches.cancel("batch_abc123")
puts batch.status # => "cancelling"

​
Parameters

​
batch_id
string
required
The ID of the batch to cancel

​
Examples

​
Complete batch workflow

# Create JSONL file with requests
requests = [
  {
    custom_id: "request-1",
    method: "POST",
    url: "/v1/responses",
    body: {
      model: "gpt-4o",
      input: "What is the capital of France?"
    }
  },
  {
    custom_id: "request-2",
    method: "POST",
    url: "/v1/responses",
    body: {
      model: "gpt-4o",
      input: "What is 2+2?"
    }
  }
]

# Write to file
File.open("batch_requests.jsonl", "w") do |f|
  requests.each { |req| f.puts(req.to_json) }
end

Build docs developers (and LLMs) love

Get started for freeTalk to us