Batches

Create batch

batches.create(**kwargs) -> Batch

post /batches

Creates and executes a batch from an uploaded file of requests

Parameters

completion_window: :"24h"

The time frame within which the batch should be processed. Currently only 24h is supported.
- :"24h"
endpoint: :"/v1/responses" | :"/v1/chat/completions" | :"/v1/embeddings" | 5 more

The endpoint to be used for all requests in the batch. Currently /v1/responses, /v1/chat/completions, /v1/embeddings, /v1/completions, /v1/moderations, /v1/images/generations, /v1/images/edits, and /v1/videos are supported. Note that /v1/embeddings batches are also restricted to a maximum of 50,000 embedding inputs across all requests in the batch.
- :"/v1/responses"
- :"/v1/chat/completions"
- :"/v1/embeddings"
- :"/v1/completions"
- :"/v1/moderations"
- :"/v1/images/generations"
- :"/v1/images/edits"
- :"/v1/videos"
input_file_id: String

The ID of an uploaded file that contains requests for the new batch.

See upload file for how to upload a file.

Your input file must be formatted as a JSONL file, and must be uploaded with the purpose batch. The file can contain up to 50,000 requests, and can be up to 200 MB in size.
metadata: Metadata

Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format, and querying for objects via API or the dashboard.

Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters.
output_expires_after: OutputExpiresAfter{ anchor, seconds}

The expiration policy for the output and/or error file that are generated for a batch.
- anchor: :created_at
  
  Anchor timestamp after which the expiration policy applies. Supported anchors: created_at. Note that the anchor is the file creation time, not the time the batch is created.
  - :created_at
- seconds: Integer
  
  The number of seconds after the anchor time that the file will expire. Must be between 3600 (1 hour) and 2592000 (30 days).

Returns

class Batch
- id: String
- completion_window: String
  
  The time frame within which the batch should be processed.
- created_at: Integer
  
  The Unix timestamp (in seconds) for when the batch was created.
- endpoint: String
  
  The OpenAI API endpoint used by the batch.
- input_file_id: String
  
  The ID of the input file for the batch.
- object: :batch
  
  The object type, which is always batch.
  - :batch
- status: :validating | :failed | :in_progress | 5 more
  
  The current status of the batch.
  - :validating
  - :failed
  - :in_progress
  - :finalizing
  - :completed
  - :expired
  - :cancelling
  - :cancelled
- cancelled_at: Integer
  
  The Unix timestamp (in seconds) for when the batch was cancelled.
- cancelling_at: Integer
  
  The Unix timestamp (in seconds) for when the batch started cancelling.
- completed_at: Integer
  
  The Unix timestamp (in seconds) for when the batch was completed.
- error_file_id: String
  
  The ID of the file containing the outputs of requests with errors.
- errors: Errors{ data, object}
  - data: Array[BatchError]
    - code: String
      
      An error code identifying the error type.
    - line: Integer
      
      The line number of the input file where the error occurred, if applicable.
    - message: String
      
      A human-readable message providing more details about the error.
    - param: String
      
      The name of the parameter that caused the error, if applicable.
  - object: String
    
    The object type, which is always list.
- expired_at: Integer
  
  The Unix timestamp (in seconds) for when the batch expired.
- expires_at: Integer
  
  The Unix timestamp (in seconds) for when the batch will expire.
- failed_at: Integer
  
  The Unix timestamp (in seconds) for when the batch failed.
- finalizing_at: Integer
  
  The Unix timestamp (in seconds) for when the batch started finalizing.
- in_progress_at: Integer
  
  The Unix timestamp (in seconds) for when the batch started processing.
- metadata: Metadata
  
  Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format, and querying for objects via API or the dashboard.
  
  Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters.
- model: String
  
  Model ID used to process the batch, like gpt-5-2025-08-07. OpenAI offers a wide range of models with different capabilities, performance characteristics, and price points. Refer to the model guide to browse and compare available models.
- output_file_id: String
  
  The ID of the file containing the outputs of successfully executed requests.
- request_counts: BatchRequestCounts
  
  The request counts for different statuses within the batch.
  - completed: Integer
    
    Number of requests that have been completed successfully.
  - failed: Integer
    
    Number of requests that have failed.
  - total: Integer
    
    Total number of requests in the batch.
- usage: BatchUsage
  
  Represents token usage details including input tokens, output tokens, a breakdown of output tokens, and the total tokens used. Only populated on batches created after September 7, 2025.
  - input_tokens: Integer
    
    The number of input tokens.
  - input_tokens_details: InputTokensDetails{ cached_tokens}
    
    A detailed breakdown of the input tokens.
    - cached_tokens: Integer
      
      The number of tokens that were retrieved from the cache. More on prompt caching.
  - output_tokens: Integer
    
    The number of output tokens.
  - output_tokens_details: OutputTokensDetails{ reasoning_tokens}
    
    A detailed breakdown of the output tokens.
    - reasoning_tokens: Integer
      
      The number of reasoning tokens.
  - total_tokens: Integer
    
    The total number of tokens used.

Example

require "openai"

openai = OpenAI::Client.new(api_key: "My API Key")

batch = openai.batches.create(
  completion_window: :"24h",
  endpoint: :"/v1/responses",
  input_file_id: "input_file_id"
)

puts(batch)

Response

{
  "id": "id",
  "completion_window": "completion_window",
  "created_at": 0,
  "endpoint": "endpoint",
  "input_file_id": "input_file_id",
  "object": "batch",
  "status": "validating",
  "cancelled_at": 0,
  "cancelling_at": 0,
  "completed_at": 0,
  "error_file_id": "error_file_id",
  "errors": {
    "data": [
      {
        "code": "code",
        "line": 0,
        "message": "message",
        "param": "param"
      }
    ],
    "object": "object"
  },
  "expired_at": 0,
  "expires_at": 0,
  "failed_at": 0,
  "finalizing_at": 0,
  "in_progress_at": 0,
  "metadata": {
    "foo": "string"
  },
  "model": "model",
  "output_file_id": "output_file_id",
  "request_counts": {
    "completed": 0,
    "failed": 0,
    "total": 0
  },
  "usage": {
    "input_tokens": 0,
    "input_tokens_details": {
      "cached_tokens": 0
    },
    "output_tokens": 0,
    "output_tokens_details": {
      "reasoning_tokens": 0
    },
    "total_tokens": 0
  }
}

Retrieve batch

batches.retrieve(batch_id) -> Batch

get /batches/{batch_id}

Retrieves a batch.

Parameters

batch_id: String

Returns

class Batch
- id: String
- completion_window: String
  
  The time frame within which the batch should be processed.
- created_at: Integer
  
  The Unix timestamp (in seconds) for when the batch was created.
- endpoint: String
  
  The OpenAI API endpoint used by the batch.
- input_file_id: String
  
  The ID of the input file for the batch.
- object: :batch
  
  The object type, which is always batch.
  - :batch
- status: :validating | :failed | :in_progress | 5 more
  
  The current status of the batch.
  - :validating
  - :failed
  - :in_progress
  - :finalizing
  - :completed
  - :expired
  - :cancelling
  - :cancelled
- cancelled_at: Integer
  
  The Unix timestamp (in seconds) for when the batch was cancelled.
- cancelling_at: Integer
  
  The Unix timestamp (in seconds) for when the batch started cancelling.
- completed_at: Integer
  
  The Unix timestamp (in seconds) for when the batch was completed.
- error_file_id: String
  
  The ID of the file containing the outputs of requests with errors.
- errors: Errors{ data, object}
  - data: Array[BatchError]
    - code: String
      
      An error code identifying the error type.
    - line: Integer
      
      The line number of the input file where the error occurred, if applicable.
    - message: String
      
      A human-readable message providing more details about the error.
    - param: String
      
      The name of the parameter that caused the error, if applicable.
  - object: String
    
    The object type, which is always list.
- expired_at: Integer
  
  The Unix timestamp (in seconds) for when the batch expired.
- expires_at: Integer
  
  The Unix timestamp (in seconds) for when the batch will expire.
- failed_at: Integer
  
  The Unix timestamp (in seconds) for when the batch failed.
- finalizing_at: Integer
  
  The Unix timestamp (in seconds) for when the batch started finalizing.
- in_progress_at: Integer
  
  The Unix timestamp (in seconds) for when the batch started processing.
- metadata: Metadata
  
  Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format, and querying for objects via API or the dashboard.
  
  Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters.
- model: String
  
  Model ID used to process the batch, like gpt-5-2025-08-07. OpenAI offers a wide range of models with different capabilities, performance characteristics, and price points. Refer to the model guide to browse and compare available models.
- output_file_id: String
  
  The ID of the file containing the outputs of successfully executed requests.
- request_counts: BatchRequestCounts
  
  The request counts for different statuses within the batch.
  - completed: Integer
    
    Number of requests that have been completed successfully.
  - failed: Integer
    
    Number of requests that have failed.
  - total: Integer
    
    Total number of requests in the batch.
- usage: BatchUsage
  
  Represents token usage details including input tokens, output tokens, a breakdown of output tokens, and the total tokens used. Only populated on batches created after September 7, 2025.
  - input_tokens: Integer
    
    The number of input tokens.
  - input_tokens_details: InputTokensDetails{ cached_tokens}
    
    A detailed breakdown of the input tokens.
    - cached_tokens: Integer
      
      The number of tokens that were retrieved from the cache. More on prompt caching.
  - output_tokens: Integer
    
    The number of output tokens.
  - output_tokens_details: OutputTokensDetails{ reasoning_tokens}
    
    A detailed breakdown of the output tokens.
    - reasoning_tokens: Integer
      
      The number of reasoning tokens.
  - total_tokens: Integer
    
    The total number of tokens used.

Example

require "openai"

openai = OpenAI::Client.new(api_key: "My API Key")

batch = openai.batches.retrieve("batch_id")

puts(batch)

Response

{
  "id": "id",
  "completion_window": "completion_window",
  "created_at": 0,
  "endpoint": "endpoint",
  "input_file_id": "input_file_id",
  "object": "batch",
  "status": "validating",
  "cancelled_at": 0,
  "cancelling_at": 0,
  "completed_at": 0,
  "error_file_id": "error_file_id",
  "errors": {
    "data": [
      {
        "code": "code",
        "line": 0,
        "message": "message",
        "param": "param"
      }
    ],
    "object": "object"
  },
  "expired_at": 0,
  "expires_at": 0,
  "failed_at": 0,
  "finalizing_at": 0,
  "in_progress_at": 0,
  "metadata": {
    "foo": "string"
  },
  "model": "model",
  "output_file_id": "output_file_id",
  "request_counts": {
    "completed": 0,
    "failed": 0,
    "total": 0
  },
  "usage": {
    "input_tokens": 0,
    "input_tokens_details": {
      "cached_tokens": 0
    },
    "output_tokens": 0,
    "output_tokens_details": {
      "reasoning_tokens": 0
    },
    "total_tokens": 0
  }
}

Cancel batch

batches.cancel(batch_id) -> Batch

post /batches/{batch_id}/cancel

Cancels an in-progress batch. The batch will be in status cancelling for up to 10 minutes, before changing to cancelled, where it will have partial results (if any) available in the output file.

Parameters

batch_id: String

Returns

class Batch
- id: String
- completion_window: String
  
  The time frame within which the batch should be processed.
- created_at: Integer
  
  The Unix timestamp (in seconds) for when the batch was created.
- endpoint: String
  
  The OpenAI API endpoint used by the batch.
- input_file_id: String
  
  The ID of the input file for the batch.
- object: :batch
  
  The object type, which is always batch.
  - :batch
- status: :validating | :failed | :in_progress | 5 more
  
  The current status of the batch.
  - :validating
  - :failed
  - :in_progress
  - :finalizing
  - :completed
  - :expired
  - :cancelling
  - :cancelled
- cancelled_at: Integer
  
  The Unix timestamp (in seconds) for when the batch was cancelled.
- cancelling_at: Integer
  
  The Unix timestamp (in seconds) for when the batch started cancelling.
- completed_at: Integer
  
  The Unix timestamp (in seconds) for when the batch was completed.
- error_file_id: String
  
  The ID of the file containing the outputs of requests with errors.
- errors: Errors{ data, object}
  - data: Array[BatchError]
    - code: String
      
      An error code identifying the error type.
    - line: Integer
      
      The line number of the input file where the error occurred, if applicable.
    - message: String
      
      A human-readable message providing more details about the error.
    - param: String
      
      The name of the parameter that caused the error, if applicable.
  - object: String
    
    The object type, which is always list.
- expired_at: Integer
  
  The Unix timestamp (in seconds) for when the batch expired.
- expires_at: Integer
  
  The Unix timestamp (in seconds) for when the batch will expire.
- failed_at: Integer
  
  The Unix timestamp (in seconds) for when the batch failed.
- finalizing_at: Integer
  
  The Unix timestamp (in seconds) for when the batch started finalizing.
- in_progress_at: Integer
  
  The Unix timestamp (in seconds) for when the batch started processing.
- metadata: Metadata
  
  Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format, and querying for objects via API or the dashboard.
  
  Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters.
- model: String
  
  Model ID used to process the batch, like gpt-5-2025-08-07. OpenAI offers a wide range of models with different capabilities, performance characteristics, and price points. Refer to the model guide to browse and compare available models.
- output_file_id: String
  
  The ID of the file containing the outputs of successfully executed requests.
- request_counts: BatchRequestCounts
  
  The request counts for different statuses within the batch.
  - completed: Integer
    
    Number of requests that have been completed successfully.
  - failed: Integer
    
    Number of requests that have failed.
  - total: Integer
    
    Total number of requests in the batch.
- usage: BatchUsage
  
  Represents token usage details including input tokens, output tokens, a breakdown of output tokens, and the total tokens used. Only populated on batches created after September 7, 2025.
  - input_tokens: Integer
    
    The number of input tokens.
  - input_tokens_details: InputTokensDetails{ cached_tokens}
    
    A detailed breakdown of the input tokens.
    - cached_tokens: Integer
      
      The number of tokens that were retrieved from the cache. More on prompt caching.
  - output_tokens: Integer
    
    The number of output tokens.
  - output_tokens_details: OutputTokensDetails{ reasoning_tokens}
    
    A detailed breakdown of the output tokens.
    - reasoning_tokens: Integer
      
      The number of reasoning tokens.
  - total_tokens: Integer
    
    The total number of tokens used.

Example

require "openai"

openai = OpenAI::Client.new(api_key: "My API Key")

batch = openai.batches.cancel("batch_id")

puts(batch)

Response

{
  "id": "id",
  "completion_window": "completion_window",
  "created_at": 0,
  "endpoint": "endpoint",
  "input_file_id": "input_file_id",
  "object": "batch",
  "status": "validating",
  "cancelled_at": 0,
  "cancelling_at": 0,
  "completed_at": 0,
  "error_file_id": "error_file_id",
  "errors": {
    "data": [
      {
        "code": "code",
        "line": 0,
        "message": "message",
        "param": "param"
      }
    ],
    "object": "object"
  },
  "expired_at": 0,
  "expires_at": 0,
  "failed_at": 0,
  "finalizing_at": 0,
  "in_progress_at": 0,
  "metadata": {
    "foo": "string"
  },
  "model": "model",
  "output_file_id": "output_file_id",
  "request_counts": {
    "completed": 0,
    "failed": 0,
    "total": 0
  },
  "usage": {
    "input_tokens": 0,
    "input_tokens_details": {
      "cached_tokens": 0
    },
    "output_tokens": 0,
    "output_tokens_details": {
      "reasoning_tokens": 0
    },
    "total_tokens": 0
  }
}

List batches

batches.list(**kwargs) -> CursorPage<Batch>

get /batches

List your organization's batches.

Parameters

after: String

A cursor for use in pagination. after is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list.
limit: Integer

A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20.

Returns

class Batch
- id: String
- completion_window: String
  
  The time frame within which the batch should be processed.
- created_at: Integer
  
  The Unix timestamp (in seconds) for when the batch was created.
- endpoint: String
  
  The OpenAI API endpoint used by the batch.
- input_file_id: String
  
  The ID of the input file for the batch.
- object: :batch
  
  The object type, which is always batch.
  - :batch
- status: :validating | :failed | :in_progress | 5 more
  
  The current status of the batch.
  - :validating
  - :failed
  - :in_progress
  - :finalizing
  - :completed
  - :expired
  - :cancelling
  - :cancelled
- cancelled_at: Integer
  
  The Unix timestamp (in seconds) for when the batch was cancelled.
- cancelling_at: Integer
  
  The Unix timestamp (in seconds) for when the batch started cancelling.
- completed_at: Integer
  
  The Unix timestamp (in seconds) for when the batch was completed.
- error_file_id: String
  
  The ID of the file containing the outputs of requests with errors.
- errors: Errors{ data, object}
  - data: Array[BatchError]
    - code: String
      
      An error code identifying the error type.
    - line: Integer
      
      The line number of the input file where the error occurred, if applicable.
    - message: String
      
      A human-readable message providing more details about the error.
    - param: String
      
      The name of the parameter that caused the error, if applicable.
  - object: String
    
    The object type, which is always list.
- expired_at: Integer
  
  The Unix timestamp (in seconds) for when the batch expired.
- expires_at: Integer
  
  The Unix timestamp (in seconds) for when the batch will expire.
- failed_at: Integer
  
  The Unix timestamp (in seconds) for when the batch failed.
- finalizing_at: Integer
  
  The Unix timestamp (in seconds) for when the batch started finalizing.
- in_progress_at: Integer
  
  The Unix timestamp (in seconds) for when the batch started processing.
- metadata: Metadata
  
  Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format, and querying for objects via API or the dashboard.
  
  Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters.
- model: String
  
  Model ID used to process the batch, like gpt-5-2025-08-07. OpenAI offers a wide range of models with different capabilities, performance characteristics, and price points. Refer to the model guide to browse and compare available models.
- output_file_id: String
  
  The ID of the file containing the outputs of successfully executed requests.
- request_counts: BatchRequestCounts
  
  The request counts for different statuses within the batch.
  - completed: Integer
    
    Number of requests that have been completed successfully.
  - failed: Integer
    
    Number of requests that have failed.
  - total: Integer
    
    Total number of requests in the batch.
- usage: BatchUsage
  
  Represents token usage details including input tokens, output tokens, a breakdown of output tokens, and the total tokens used. Only populated on batches created after September 7, 2025.
  - input_tokens: Integer
    
    The number of input tokens.
  - input_tokens_details: InputTokensDetails{ cached_tokens}
    
    A detailed breakdown of the input tokens.
    - cached_tokens: Integer
      
      The number of tokens that were retrieved from the cache. More on prompt caching.
  - output_tokens: Integer
    
    The number of output tokens.
  - output_tokens_details: OutputTokensDetails{ reasoning_tokens}
    
    A detailed breakdown of the output tokens.
    - reasoning_tokens: Integer
      
      The number of reasoning tokens.
  - total_tokens: Integer
    
    The total number of tokens used.

Example

require "openai"

openai = OpenAI::Client.new(api_key: "My API Key")

page = openai.batches.list

puts(page)

Response

{
  "data": [
    {
      "id": "id",
      "completion_window": "completion_window",
      "created_at": 0,
      "endpoint": "endpoint",
      "input_file_id": "input_file_id",
      "object": "batch",
      "status": "validating",
      "cancelled_at": 0,
      "cancelling_at": 0,
      "completed_at": 0,
      "error_file_id": "error_file_id",
      "errors": {
        "data": [
          {
            "code": "code",
            "line": 0,
            "message": "message",
            "param": "param"
          }
        ],
        "object": "object"
      },
      "expired_at": 0,
      "expires_at": 0,
      "failed_at": 0,
      "finalizing_at": 0,
      "in_progress_at": 0,
      "metadata": {
        "foo": "string"
      },
      "model": "model",
      "output_file_id": "output_file_id",
      "request_counts": {
        "completed": 0,
        "failed": 0,
        "total": 0
      },
      "usage": {
        "input_tokens": 0,
        "input_tokens_details": {
          "cached_tokens": 0
        },
        "output_tokens": 0,
        "output_tokens_details": {
          "reasoning_tokens": 0
        },
        "total_tokens": 0
      }
    }
  ],
  "has_more": true,
  "object": "list",
  "first_id": "batch_abc123",
  "last_id": "batch_abc456"
}

Domain Types

Batch

class Batch
- id: String
- completion_window: String
  
  The time frame within which the batch should be processed.
- created_at: Integer
  
  The Unix timestamp (in seconds) for when the batch was created.
- endpoint: String
  
  The OpenAI API endpoint used by the batch.
- input_file_id: String
  
  The ID of the input file for the batch.
- object: :batch
  
  The object type, which is always batch.
  - :batch
- status: :validating | :failed | :in_progress | 5 more
  
  The current status of the batch.
  - :validating
  - :failed
  - :in_progress
  - :finalizing
  - :completed
  - :expired
  - :cancelling
  - :cancelled
- cancelled_at: Integer
  
  The Unix timestamp (in seconds) for when the batch was cancelled.
- cancelling_at: Integer
  
  The Unix timestamp (in seconds) for when the batch started cancelling.
- completed_at: Integer
  
  The Unix timestamp (in seconds) for when the batch was completed.
- error_file_id: String
  
  The ID of the file containing the outputs of requests with errors.
- errors: Errors{ data, object}
  - data: Array[BatchError]
    - code: String
      
      An error code identifying the error type.
    - line: Integer
      
      The line number of the input file where the error occurred, if applicable.
    - message: String
      
      A human-readable message providing more details about the error.
    - param: String
      
      The name of the parameter that caused the error, if applicable.
  - object: String
    
    The object type, which is always list.
- expired_at: Integer
  
  The Unix timestamp (in seconds) for when the batch expired.
- expires_at: Integer
  
  The Unix timestamp (in seconds) for when the batch will expire.
- failed_at: Integer
  
  The Unix timestamp (in seconds) for when the batch failed.
- finalizing_at: Integer
  
  The Unix timestamp (in seconds) for when the batch started finalizing.
- in_progress_at: Integer
  
  The Unix timestamp (in seconds) for when the batch started processing.
- metadata: Metadata
  
  Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format, and querying for objects via API or the dashboard.
  
  Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters.
- model: String
  
  Model ID used to process the batch, like gpt-5-2025-08-07. OpenAI offers a wide range of models with different capabilities, performance characteristics, and price points. Refer to the model guide to browse and compare available models.
- output_file_id: String
  
  The ID of the file containing the outputs of successfully executed requests.
- request_counts: BatchRequestCounts
  
  The request counts for different statuses within the batch.
  - completed: Integer
    
    Number of requests that have been completed successfully.
  - failed: Integer
    
    Number of requests that have failed.
  - total: Integer
    
    Total number of requests in the batch.
- usage: BatchUsage
  
  Represents token usage details including input tokens, output tokens, a breakdown of output tokens, and the total tokens used. Only populated on batches created after September 7, 2025.
  - input_tokens: Integer
    
    The number of input tokens.
  - input_tokens_details: InputTokensDetails{ cached_tokens}
    
    A detailed breakdown of the input tokens.
    - cached_tokens: Integer
      
      The number of tokens that were retrieved from the cache. More on prompt caching.
  - output_tokens: Integer
    
    The number of output tokens.
  - output_tokens_details: OutputTokensDetails{ reasoning_tokens}
    
    A detailed breakdown of the output tokens.
    - reasoning_tokens: Integer
      
      The number of reasoning tokens.
  - total_tokens: Integer
    
    The total number of tokens used.

Batch Error

class BatchError
- code: String
  
  An error code identifying the error type.
- line: Integer
  
  The line number of the input file where the error occurred, if applicable.
- message: String
  
  A human-readable message providing more details about the error.
- param: String
  
  The name of the parameter that caused the error, if applicable.

Batch Request Counts

class BatchRequestCounts

The request counts for different statuses within the batch.
- completed: Integer
  
  Number of requests that have been completed successfully.
- failed: Integer
  
  Number of requests that have failed.
- total: Integer
  
  Total number of requests in the batch.

Batch Usage

class BatchUsage

Represents token usage details including input tokens, output tokens, a breakdown of output tokens, and the total tokens used. Only populated on batches created after September 7, 2025.
- input_tokens: Integer
  
  The number of input tokens.
- input_tokens_details: InputTokensDetails{ cached_tokens}
  
  A detailed breakdown of the input tokens.
  - cached_tokens: Integer
    
    The number of tokens that were retrieved from the cache. More on prompt caching.
- output_tokens: Integer
  
  The number of output tokens.
- output_tokens_details: OutputTokensDetails{ reasoning_tokens}
  
  A detailed breakdown of the output tokens.
  - reasoning_tokens: Integer
    
    The number of reasoning tokens.
- total_tokens: Integer
  
  The total number of tokens used.

ruby/resources/batches/index.md +240 −24

6 6

7**post** `/batches`7**post** `/batches`

8 8

~~9Create batch~~9Creates and executes a batch from an uploaded file of requests

10 10

11### Parameters11### Parameters

12 12

133 133

134 - `errors: Errors{ data, object}`134 - `errors: Errors{ data, object}`

135 135

136 - `data: Array[untyped]`136 - `data: Array[BatchError]`

137

138 - `code: String`

139

140 An error code identifying the error type.

141

142 - `line: Integer`

143

144 The line number of the input file where the error occurred, if applicable.

145

146 - `message: String`

147

148 A human-readable message providing more details about the error.

149

150 - `param: String`

151

152 The name of the parameter that caused the error, if applicable.

137 153

138 - `object: String`154 - `object: String`

139 155

179 195

180 The ID of the file containing the outputs of successfully executed requests.196 The ID of the file containing the outputs of successfully executed requests.

181 197

182 - `request_counts: untyped`198 - `request_counts: BatchRequestCounts`

199

200 The request counts for different statuses within the batch.

201

202 - `completed: Integer`

203

204 Number of requests that have been completed successfully.

205

206 - `failed: Integer`

207

208 Number of requests that have failed.

209

210 - `total: Integer`

211

212 Total number of requests in the batch.

183 213

184 - `usage: BatchUsage`214 - `usage: BatchUsage`

185 215

249 "error_file_id": "error_file_id",279 "error_file_id": "error_file_id",

250 "errors": {280 "errors": {

251 "data": [281 "data": [

252 {}282 {

283 "code": "code",

284 "line": 0,

285 "message": "message",

286 "param": "param"

287 }

253 ],288 ],

254 "object": "object"289 "object": "object"

255 },290 },

263 },298 },

264 "model": "model",299 "model": "model",

265 "output_file_id": "output_file_id",300 "output_file_id": "output_file_id",

266 "request_counts": {},301 "request_counts": {

302 "completed": 0,

303 "failed": 0,

304 "total": 0

305 },

267 "usage": {306 "usage": {

268 "input_tokens": 0,307 "input_tokens": 0,

269 "input_tokens_details": {308 "input_tokens_details": {

284 323

285**get** `/batches/{batch_id}`324**get** `/batches/{batch_id}`

286 325

287Retrieve batch326Retrieves a batch.

288 327

289### Parameters328### Parameters

290 329

356 395

357 - `errors: Errors{ data, object}`396 - `errors: Errors{ data, object}`

358 397

359 - `data: Array[untyped]`398 - `data: Array[BatchError]`

399

400 - `code: String`

401

402 An error code identifying the error type.

403

404 - `line: Integer`

405

406 The line number of the input file where the error occurred, if applicable.

407

408 - `message: String`

409

410 A human-readable message providing more details about the error.

411

412 - `param: String`

413

414 The name of the parameter that caused the error, if applicable.

360 415

361 - `object: String`416 - `object: String`

362 417

402 457

403 The ID of the file containing the outputs of successfully executed requests.458 The ID of the file containing the outputs of successfully executed requests.

404 459

405 - `request_counts: untyped`460 - `request_counts: BatchRequestCounts`

461

462 The request counts for different statuses within the batch.

463

464 - `completed: Integer`

465

466 Number of requests that have been completed successfully.

467

468 - `failed: Integer`

469

470 Number of requests that have failed.

471

472 - `total: Integer`

473

474 Total number of requests in the batch.

406 475

407 - `usage: BatchUsage`476 - `usage: BatchUsage`

408 477

468 "error_file_id": "error_file_id",537 "error_file_id": "error_file_id",

469 "errors": {538 "errors": {

470 "data": [539 "data": [

471 {}540 {

541 "code": "code",

542 "line": 0,

543 "message": "message",

544 "param": "param"

545 }

472 ],546 ],

473 "object": "object"547 "object": "object"

474 },548 },

482 },556 },

483 "model": "model",557 "model": "model",

484 "output_file_id": "output_file_id",558 "output_file_id": "output_file_id",

485 "request_counts": {},559 "request_counts": {

560 "completed": 0,

561 "failed": 0,

562 "total": 0

563 },

486 "usage": {564 "usage": {

487 "input_tokens": 0,565 "input_tokens": 0,

488 "input_tokens_details": {566 "input_tokens_details": {

503 581

504**post** `/batches/{batch_id}/cancel`582**post** `/batches/{batch_id}/cancel`

505 583

506Cancel batch584Cancels an in-progress batch. The batch will be in status `cancelling` for up to 10 minutes, before changing to `cancelled`, where it will have partial results (if any) available in the output file.

507 585

508### Parameters586### Parameters

509 587

575 653

576 - `errors: Errors{ data, object}`654 - `errors: Errors{ data, object}`

577 655

578 - `data: Array[untyped]`656 - `data: Array[BatchError]`

657

658 - `code: String`

659

660 An error code identifying the error type.

661

662 - `line: Integer`

663

664 The line number of the input file where the error occurred, if applicable.

665

666 - `message: String`

667

668 A human-readable message providing more details about the error.

669

670 - `param: String`

671

672 The name of the parameter that caused the error, if applicable.

579 673

580 - `object: String`674 - `object: String`

581 675

621 715

622 The ID of the file containing the outputs of successfully executed requests.716 The ID of the file containing the outputs of successfully executed requests.

623 717

624 - `request_counts: untyped`718 - `request_counts: BatchRequestCounts`

719

720 The request counts for different statuses within the batch.

721

722 - `completed: Integer`

723

724 Number of requests that have been completed successfully.

725

726 - `failed: Integer`

727

728 Number of requests that have failed.

729

730 - `total: Integer`

731

732 Total number of requests in the batch.

625 733

626 - `usage: BatchUsage`734 - `usage: BatchUsage`

627 735

687 "error_file_id": "error_file_id",795 "error_file_id": "error_file_id",

688 "errors": {796 "errors": {

689 "data": [797 "data": [

690 {}798 {

799 "code": "code",

800 "line": 0,

801 "message": "message",

802 "param": "param"

803 }

691 ],804 ],

692 "object": "object"805 "object": "object"

693 },806 },

701 },814 },

702 "model": "model",815 "model": "model",

703 "output_file_id": "output_file_id",816 "output_file_id": "output_file_id",

704 "request_counts": {},817 "request_counts": {

818 "completed": 0,

819 "failed": 0,

820 "total": 0

821 },

705 "usage": {822 "usage": {

706 "input_tokens": 0,823 "input_tokens": 0,

707 "input_tokens_details": {824 "input_tokens_details": {

722 839

723**get** `/batches`840**get** `/batches`

724 841

725List batches842List your organization's batches.

726 843

727### Parameters844### Parameters

728 845

800 917

801 - `errors: Errors{ data, object}`918 - `errors: Errors{ data, object}`

802 919

803 - `data: Array[untyped]`920 - `data: Array[BatchError]`

921

922 - `code: String`

923

924 An error code identifying the error type.

925

926 - `line: Integer`

927

928 The line number of the input file where the error occurred, if applicable.

929

930 - `message: String`

931

932 A human-readable message providing more details about the error.

933

934 - `param: String`

935

936 The name of the parameter that caused the error, if applicable.

804 937

805 - `object: String`938 - `object: String`

806 939

846 979

847 The ID of the file containing the outputs of successfully executed requests.980 The ID of the file containing the outputs of successfully executed requests.

848 981

849 - `request_counts: untyped`982 - `request_counts: BatchRequestCounts`

983

984 The request counts for different statuses within the batch.

985

986 - `completed: Integer`

987

988 Number of requests that have been completed successfully.

989

990 - `failed: Integer`

991

992 Number of requests that have failed.

993

994 - `total: Integer`

995

996 Total number of requests in the batch.

850 997

851 - `usage: BatchUsage`998 - `usage: BatchUsage`

852 999

914 "error_file_id": "error_file_id",1061 "error_file_id": "error_file_id",

915 "errors": {1062 "errors": {

916 "data": [1063 "data": [

917 {}1064 {

1065 "code": "code",

1066 "line": 0,

1067 "message": "message",

1068 "param": "param"

1069 }

918 ],1070 ],

919 "object": "object"1071 "object": "object"

920 },1072 },

928 },1080 },

929 "model": "model",1081 "model": "model",

930 "output_file_id": "output_file_id",1082 "output_file_id": "output_file_id",

931 "request_counts": {},1083 "request_counts": {

1084 "completed": 0,

1085 "failed": 0,

1086 "total": 0

1087 },

932 "usage": {1088 "usage": {

933 "input_tokens": 0,1089 "input_tokens": 0,

934 "input_tokens_details": {1090 "input_tokens_details": {

1017 1173

1018 - `errors: Errors{ data, object}`1174 - `errors: Errors{ data, object}`

1019 1175

1020 - `data: Array[untyped]`1176 - `data: Array[BatchError]`

1177

1178 - `code: String`

1179

1180 An error code identifying the error type.

1181

1182 - `line: Integer`

1183

1184 The line number of the input file where the error occurred, if applicable.

1185

1186 - `message: String`

1187

1188 A human-readable message providing more details about the error.

1189

1190 - `param: String`

1191

1192 The name of the parameter that caused the error, if applicable.

1021 1193

1022 - `object: String`1194 - `object: String`

1023 1195

1063 1235

1064 The ID of the file containing the outputs of successfully executed requests.1236 The ID of the file containing the outputs of successfully executed requests.

1065 1237

1066 - `request_counts: untyped`1238 - `request_counts: BatchRequestCounts`

1239

1240 The request counts for different statuses within the batch.

1241

1242 - `completed: Integer`

1243

1244 Number of requests that have been completed successfully.

1245

1246 - `failed: Integer`

1247

1248 Number of requests that have failed.

1249

1250 - `total: Integer`

1251

1252 Total number of requests in the batch.

1067 1253

1068 - `usage: BatchUsage`1254 - `usage: BatchUsage`

1069 1255

1102 1288

1103### Batch Error1289### Batch Error

1104 1290

1105- `BatchError = untyped`1291- `class BatchError`

1292

1293 - `code: String`

1294

1295 An error code identifying the error type.

1296

1297 - `line: Integer`

1298

1299 The line number of the input file where the error occurred, if applicable.

1300

1301 - `message: String`

1302

1303 A human-readable message providing more details about the error.

1304

1305 - `param: String`

1306

1307 The name of the parameter that caused the error, if applicable.

1106 1308

1107### Batch Request Counts1309### Batch Request Counts

1108 1310

1109- `BatchRequestCounts = untyped`1311- `class BatchRequestCounts`

1312

1313 The request counts for different statuses within the batch.

1314

1315 - `completed: Integer`

1316

1317 Number of requests that have been completed successfully.

1318

1319 - `failed: Integer`

1320

1321 Number of requests that have failed.

1322

1323 - `total: Integer`

1324

1325 Total number of requests in the batch.

1110 1326

1111### Batch Usage1327### Batch Usage

1112 1328

ruby/resources/batches/index.md 2026-07-10 23:02 UTC to 2026-07-12 06:58 UTC

Batches

Create batch

Parameters

Returns

Example

Response

Retrieve batch

Parameters

Returns

Example

Response

Cancel batch

Parameters

Returns

Example

Response

List batches

Parameters

Returns

Example

Response

Domain Types

Batch

Batch Error

Batch Request Counts

Batch Usage