Batches

Create batch

batches.create(**kwargs) -> Batch

post /batches

Create batch

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[untyped]
  - 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: untyped
- 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": [
      {}
    ],
    "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": {},
  "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}

Retrieve 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[untyped]
  - 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: untyped
- 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": [
      {}
    ],
    "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": {},
  "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

Cancel 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[untyped]
  - 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: untyped
- 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": [
      {}
    ],
    "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": {},
  "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 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[untyped]
  - 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: untyped
- 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": [
          {}
        ],
        "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": {},
      "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[untyped]
  - 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: untyped
- 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

BatchError = untyped

Batch Request Counts

BatchRequestCounts = untyped

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 +1146 −0 created

1# Batches

3## Create batch

5`batches.create(**kwargs) -> Batch`

7**post** `/batches`

9Create batch

11### Parameters

13- `completion_window: :"24h"`

15 The time frame within which the batch should be processed. Currently only `24h` is supported.

17 - `:"24h"`

19- `endpoint: :"/v1/responses" | :"/v1/chat/completions" | :"/v1/embeddings" | 5 more`

21 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.

23 - `:"/v1/responses"`

25 - `:"/v1/chat/completions"`

27 - `:"/v1/embeddings"`

29 - `:"/v1/completions"`

31 - `:"/v1/moderations"`

33 - `:"/v1/images/generations"`

35 - `:"/v1/images/edits"`

37 - `:"/v1/videos"`

39- `input_file_id: String`

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

43 See [upload file](https://platform.openai.com/docs/api-reference/files/create) for how to upload a file.

45 Your input file must be formatted as a [JSONL file](https://platform.openai.com/docs/api-reference/batch/request-input), 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.

47- `metadata: Metadata`

49 Set of 16 key-value pairs that can be attached to an object. This can be

50 useful for storing additional information about the object in a structured

51 format, and querying for objects via API or the dashboard.

53 Keys are strings with a maximum length of 64 characters. Values are strings

54 with a maximum length of 512 characters.

56- `output_expires_after: OutputExpiresAfter{ anchor, seconds}`

58 The expiration policy for the output and/or error file that are generated for a batch.

60 - `anchor: :created_at`

62 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.

64 - `:created_at`

66 - `seconds: Integer`

68 The number of seconds after the anchor time that the file will expire. Must be between 3600 (1 hour) and 2592000 (30 days).

70### Returns

72- `class Batch`

74 - `id: String`

76 - `completion_window: String`

78 The time frame within which the batch should be processed.

80 - `created_at: Integer`

82 The Unix timestamp (in seconds) for when the batch was created.

84 - `endpoint: String`

86 The OpenAI API endpoint used by the batch.

88 - `input_file_id: String`

90 The ID of the input file for the batch.

92 - `object: :batch`

94 The object type, which is always `batch`.

96 - `:batch`

98 - `status: :validating | :failed | :in_progress | 5 more`

100 The current status of the batch.

101

102 - `:validating`

103

104 - `:failed`

105

106 - `:in_progress`

107

108 - `:finalizing`

109

110 - `:completed`

111

112 - `:expired`

113

114 - `:cancelling`

115

116 - `:cancelled`

117

118 - `cancelled_at: Integer`

119

120 The Unix timestamp (in seconds) for when the batch was cancelled.

121

122 - `cancelling_at: Integer`

123

124 The Unix timestamp (in seconds) for when the batch started cancelling.

125

126 - `completed_at: Integer`

127

128 The Unix timestamp (in seconds) for when the batch was completed.

129

130 - `error_file_id: String`

131

132 The ID of the file containing the outputs of requests with errors.

133

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

135

136 - `data: Array[untyped]`

137

138 - `object: String`

139

140 The object type, which is always `list`.

141

142 - `expired_at: Integer`

143

144 The Unix timestamp (in seconds) for when the batch expired.

145

146 - `expires_at: Integer`

147

148 The Unix timestamp (in seconds) for when the batch will expire.

149

150 - `failed_at: Integer`

151

152 The Unix timestamp (in seconds) for when the batch failed.

153

154 - `finalizing_at: Integer`

155

156 The Unix timestamp (in seconds) for when the batch started finalizing.

157

158 - `in_progress_at: Integer`

159

160 The Unix timestamp (in seconds) for when the batch started processing.

161

162 - `metadata: Metadata`

163

164 Set of 16 key-value pairs that can be attached to an object. This can be

165 useful for storing additional information about the object in a structured

166 format, and querying for objects via API or the dashboard.

167

168 Keys are strings with a maximum length of 64 characters. Values are strings

169 with a maximum length of 512 characters.

170

171 - `model: String`

172

173 Model ID used to process the batch, like `gpt-5-2025-08-07`. OpenAI

174 offers a wide range of models with different capabilities, performance

175 characteristics, and price points. Refer to the [model

176 guide](https://platform.openai.com/docs/models) to browse and compare available models.

177

178 - `output_file_id: String`

179

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

181

182 - `request_counts: untyped`

183

184 - `usage: BatchUsage`

185

186 Represents token usage details including input tokens, output tokens, a

187 breakdown of output tokens, and the total tokens used. Only populated on

188 batches created after September 7, 2025.

189

190 - `input_tokens: Integer`

191

192 The number of input tokens.

193

194 - `input_tokens_details: InputTokensDetails{ cached_tokens}`

195

196 A detailed breakdown of the input tokens.

197

198 - `cached_tokens: Integer`

199

200 The number of tokens that were retrieved from the cache. [More on

201 prompt caching](https://platform.openai.com/docs/guides/prompt-caching).

202

203 - `output_tokens: Integer`

204

205 The number of output tokens.

206

207 - `output_tokens_details: OutputTokensDetails{ reasoning_tokens}`

208

209 A detailed breakdown of the output tokens.

210

211 - `reasoning_tokens: Integer`

212

213 The number of reasoning tokens.

214

215 - `total_tokens: Integer`

216

217 The total number of tokens used.

218

219### Example

220

221```ruby

222require "openai"

223

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

225

226batch = openai.batches.create(

227 completion_window: :"24h",

228 endpoint: :"/v1/responses",

229 input_file_id: "input_file_id"

230)

231

232puts(batch)

233```

234

235#### Response

236

237```json

238{

239 "id": "id",

240 "completion_window": "completion_window",

241 "created_at": 0,

242 "endpoint": "endpoint",

243 "input_file_id": "input_file_id",

244 "object": "batch",

245 "status": "validating",

246 "cancelled_at": 0,

247 "cancelling_at": 0,

248 "completed_at": 0,

249 "error_file_id": "error_file_id",

250 "errors": {

251 "data": [

252 {}

253 ],

254 "object": "object"

255 },

256 "expired_at": 0,

257 "expires_at": 0,

258 "failed_at": 0,

259 "finalizing_at": 0,

260 "in_progress_at": 0,

261 "metadata": {

262 "foo": "string"

263 },

264 "model": "model",

265 "output_file_id": "output_file_id",

266 "request_counts": {},

267 "usage": {

268 "input_tokens": 0,

269 "input_tokens_details": {

270 "cached_tokens": 0

271 },

272 "output_tokens": 0,

273 "output_tokens_details": {

274 "reasoning_tokens": 0

275 },

276 "total_tokens": 0

277 }

278}

279```

280

281## Retrieve batch

282

283`batches.retrieve(batch_id) -> Batch`

284

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

286

287Retrieve batch

288

289### Parameters

290

291- `batch_id: String`

292

293### Returns

294

295- `class Batch`

296

297 - `id: String`

298

299 - `completion_window: String`

300

301 The time frame within which the batch should be processed.

302

303 - `created_at: Integer`

304

305 The Unix timestamp (in seconds) for when the batch was created.

306

307 - `endpoint: String`

308

309 The OpenAI API endpoint used by the batch.

310

311 - `input_file_id: String`

312

313 The ID of the input file for the batch.

314

315 - `object: :batch`

316

317 The object type, which is always `batch`.

318

319 - `:batch`

320

321 - `status: :validating | :failed | :in_progress | 5 more`

322

323 The current status of the batch.

324

325 - `:validating`

326

327 - `:failed`

328

329 - `:in_progress`

330

331 - `:finalizing`

332

333 - `:completed`

334

335 - `:expired`

336

337 - `:cancelling`

338

339 - `:cancelled`

340

341 - `cancelled_at: Integer`

342

343 The Unix timestamp (in seconds) for when the batch was cancelled.

344

345 - `cancelling_at: Integer`

346

347 The Unix timestamp (in seconds) for when the batch started cancelling.

348

349 - `completed_at: Integer`

350

351 The Unix timestamp (in seconds) for when the batch was completed.

352

353 - `error_file_id: String`

354

355 The ID of the file containing the outputs of requests with errors.

356

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

358

359 - `data: Array[untyped]`

360

361 - `object: String`

362

363 The object type, which is always `list`.

364

365 - `expired_at: Integer`

366

367 The Unix timestamp (in seconds) for when the batch expired.

368

369 - `expires_at: Integer`

370

371 The Unix timestamp (in seconds) for when the batch will expire.

372

373 - `failed_at: Integer`

374

375 The Unix timestamp (in seconds) for when the batch failed.

376

377 - `finalizing_at: Integer`

378

379 The Unix timestamp (in seconds) for when the batch started finalizing.

380

381 - `in_progress_at: Integer`

382

383 The Unix timestamp (in seconds) for when the batch started processing.

384

385 - `metadata: Metadata`

386

387 Set of 16 key-value pairs that can be attached to an object. This can be

388 useful for storing additional information about the object in a structured

389 format, and querying for objects via API or the dashboard.

390

391 Keys are strings with a maximum length of 64 characters. Values are strings

392 with a maximum length of 512 characters.

393

394 - `model: String`

395

396 Model ID used to process the batch, like `gpt-5-2025-08-07`. OpenAI

397 offers a wide range of models with different capabilities, performance

398 characteristics, and price points. Refer to the [model

399 guide](https://platform.openai.com/docs/models) to browse and compare available models.

400

401 - `output_file_id: String`

402

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

404

405 - `request_counts: untyped`

406

407 - `usage: BatchUsage`

408

409 Represents token usage details including input tokens, output tokens, a

410 breakdown of output tokens, and the total tokens used. Only populated on

411 batches created after September 7, 2025.

412

413 - `input_tokens: Integer`

414

415 The number of input tokens.

416

417 - `input_tokens_details: InputTokensDetails{ cached_tokens}`

418

419 A detailed breakdown of the input tokens.

420

421 - `cached_tokens: Integer`

422

423 The number of tokens that were retrieved from the cache. [More on

424 prompt caching](https://platform.openai.com/docs/guides/prompt-caching).

425

426 - `output_tokens: Integer`

427

428 The number of output tokens.

429

430 - `output_tokens_details: OutputTokensDetails{ reasoning_tokens}`

431

432 A detailed breakdown of the output tokens.

433

434 - `reasoning_tokens: Integer`

435

436 The number of reasoning tokens.

437

438 - `total_tokens: Integer`

439

440 The total number of tokens used.

441

442### Example

443

444```ruby

445require "openai"

446

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

448

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

450

451puts(batch)

452```

453

454#### Response

455

456```json

457{

458 "id": "id",

459 "completion_window": "completion_window",

460 "created_at": 0,

461 "endpoint": "endpoint",

462 "input_file_id": "input_file_id",

463 "object": "batch",

464 "status": "validating",

465 "cancelled_at": 0,

466 "cancelling_at": 0,

467 "completed_at": 0,

468 "error_file_id": "error_file_id",

469 "errors": {

470 "data": [

471 {}

472 ],

473 "object": "object"

474 },

475 "expired_at": 0,

476 "expires_at": 0,

477 "failed_at": 0,

478 "finalizing_at": 0,

479 "in_progress_at": 0,

480 "metadata": {

481 "foo": "string"

482 },

483 "model": "model",

484 "output_file_id": "output_file_id",

485 "request_counts": {},

486 "usage": {

487 "input_tokens": 0,

488 "input_tokens_details": {

489 "cached_tokens": 0

490 },

491 "output_tokens": 0,

492 "output_tokens_details": {

493 "reasoning_tokens": 0

494 },

495 "total_tokens": 0

496 }

497}

498```

499

500## Cancel batch

501

502`batches.cancel(batch_id) -> Batch`

503

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

505

506Cancel batch

507

508### Parameters

509

510- `batch_id: String`

511

512### Returns

513

514- `class Batch`

515

516 - `id: String`

517

518 - `completion_window: String`

519

520 The time frame within which the batch should be processed.

521

522 - `created_at: Integer`

523

524 The Unix timestamp (in seconds) for when the batch was created.

525

526 - `endpoint: String`

527

528 The OpenAI API endpoint used by the batch.

529

530 - `input_file_id: String`

531

532 The ID of the input file for the batch.

533

534 - `object: :batch`

535

536 The object type, which is always `batch`.

537

538 - `:batch`

539

540 - `status: :validating | :failed | :in_progress | 5 more`

541

542 The current status of the batch.

543

544 - `:validating`

545

546 - `:failed`

547

548 - `:in_progress`

549

550 - `:finalizing`

551

552 - `:completed`

553

554 - `:expired`

555

556 - `:cancelling`

557

558 - `:cancelled`

559

560 - `cancelled_at: Integer`

561

562 The Unix timestamp (in seconds) for when the batch was cancelled.

563

564 - `cancelling_at: Integer`

565

566 The Unix timestamp (in seconds) for when the batch started cancelling.

567

568 - `completed_at: Integer`

569

570 The Unix timestamp (in seconds) for when the batch was completed.

571

572 - `error_file_id: String`

573

574 The ID of the file containing the outputs of requests with errors.

575

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

577

578 - `data: Array[untyped]`

579

580 - `object: String`

581

582 The object type, which is always `list`.

583

584 - `expired_at: Integer`

585

586 The Unix timestamp (in seconds) for when the batch expired.

587

588 - `expires_at: Integer`

589

590 The Unix timestamp (in seconds) for when the batch will expire.

591

592 - `failed_at: Integer`

593

594 The Unix timestamp (in seconds) for when the batch failed.

595

596 - `finalizing_at: Integer`

597

598 The Unix timestamp (in seconds) for when the batch started finalizing.

599

600 - `in_progress_at: Integer`

601

602 The Unix timestamp (in seconds) for when the batch started processing.

603

604 - `metadata: Metadata`

605

606 Set of 16 key-value pairs that can be attached to an object. This can be

607 useful for storing additional information about the object in a structured

608 format, and querying for objects via API or the dashboard.

609

610 Keys are strings with a maximum length of 64 characters. Values are strings

611 with a maximum length of 512 characters.

612

613 - `model: String`

614

615 Model ID used to process the batch, like `gpt-5-2025-08-07`. OpenAI

616 offers a wide range of models with different capabilities, performance

617 characteristics, and price points. Refer to the [model

618 guide](https://platform.openai.com/docs/models) to browse and compare available models.

619

620 - `output_file_id: String`

621

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

623

624 - `request_counts: untyped`

625

626 - `usage: BatchUsage`

627

628 Represents token usage details including input tokens, output tokens, a

629 breakdown of output tokens, and the total tokens used. Only populated on

630 batches created after September 7, 2025.

631

632 - `input_tokens: Integer`

633

634 The number of input tokens.

635

636 - `input_tokens_details: InputTokensDetails{ cached_tokens}`

637

638 A detailed breakdown of the input tokens.

639

640 - `cached_tokens: Integer`

641

642 The number of tokens that were retrieved from the cache. [More on

643 prompt caching](https://platform.openai.com/docs/guides/prompt-caching).

644

645 - `output_tokens: Integer`

646

647 The number of output tokens.

648

649 - `output_tokens_details: OutputTokensDetails{ reasoning_tokens}`

650

651 A detailed breakdown of the output tokens.

652

653 - `reasoning_tokens: Integer`

654

655 The number of reasoning tokens.

656

657 - `total_tokens: Integer`

658

659 The total number of tokens used.

660

661### Example

662

663```ruby

664require "openai"

665

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

667

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

669

670puts(batch)

671```

672

673#### Response

674

675```json

676{

677 "id": "id",

678 "completion_window": "completion_window",

679 "created_at": 0,

680 "endpoint": "endpoint",

681 "input_file_id": "input_file_id",

682 "object": "batch",

683 "status": "validating",

684 "cancelled_at": 0,

685 "cancelling_at": 0,

686 "completed_at": 0,

687 "error_file_id": "error_file_id",

688 "errors": {

689 "data": [

690 {}

691 ],

692 "object": "object"

693 },

694 "expired_at": 0,

695 "expires_at": 0,

696 "failed_at": 0,

697 "finalizing_at": 0,

698 "in_progress_at": 0,

699 "metadata": {

700 "foo": "string"

701 },

702 "model": "model",

703 "output_file_id": "output_file_id",

704 "request_counts": {},

705 "usage": {

706 "input_tokens": 0,

707 "input_tokens_details": {

708 "cached_tokens": 0

709 },

710 "output_tokens": 0,

711 "output_tokens_details": {

712 "reasoning_tokens": 0

713 },

714 "total_tokens": 0

715 }

716}

717```

718

719## List batches

720

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

722

723**get** `/batches`

724

725List batches

726

727### Parameters

728

729- `after: String`

730

731 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.

732

733- `limit: Integer`

734

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

736

737### Returns

738

739- `class Batch`

740

741 - `id: String`

742

743 - `completion_window: String`

744

745 The time frame within which the batch should be processed.

746

747 - `created_at: Integer`

748

749 The Unix timestamp (in seconds) for when the batch was created.

750

751 - `endpoint: String`

752

753 The OpenAI API endpoint used by the batch.

754

755 - `input_file_id: String`

756

757 The ID of the input file for the batch.

758

759 - `object: :batch`

760

761 The object type, which is always `batch`.

762

763 - `:batch`

764

765 - `status: :validating | :failed | :in_progress | 5 more`

766

767 The current status of the batch.

768

769 - `:validating`

770

771 - `:failed`

772

773 - `:in_progress`

774

775 - `:finalizing`

776

777 - `:completed`

778

779 - `:expired`

780

781 - `:cancelling`

782

783 - `:cancelled`

784

785 - `cancelled_at: Integer`

786

787 The Unix timestamp (in seconds) for when the batch was cancelled.

788

789 - `cancelling_at: Integer`

790

791 The Unix timestamp (in seconds) for when the batch started cancelling.

792

793 - `completed_at: Integer`

794

795 The Unix timestamp (in seconds) for when the batch was completed.

796

797 - `error_file_id: String`

798

799 The ID of the file containing the outputs of requests with errors.

800

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

802

803 - `data: Array[untyped]`

804

805 - `object: String`

806

807 The object type, which is always `list`.

808

809 - `expired_at: Integer`

810

811 The Unix timestamp (in seconds) for when the batch expired.

812

813 - `expires_at: Integer`

814

815 The Unix timestamp (in seconds) for when the batch will expire.

816

817 - `failed_at: Integer`

818

819 The Unix timestamp (in seconds) for when the batch failed.

820

821 - `finalizing_at: Integer`

822

823 The Unix timestamp (in seconds) for when the batch started finalizing.

824

825 - `in_progress_at: Integer`

826

827 The Unix timestamp (in seconds) for when the batch started processing.

828

829 - `metadata: Metadata`

830

831 Set of 16 key-value pairs that can be attached to an object. This can be

832 useful for storing additional information about the object in a structured

833 format, and querying for objects via API or the dashboard.

834

835 Keys are strings with a maximum length of 64 characters. Values are strings

836 with a maximum length of 512 characters.

837

838 - `model: String`

839

840 Model ID used to process the batch, like `gpt-5-2025-08-07`. OpenAI

841 offers a wide range of models with different capabilities, performance

842 characteristics, and price points. Refer to the [model

843 guide](https://platform.openai.com/docs/models) to browse and compare available models.

844

845 - `output_file_id: String`

846

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

848

849 - `request_counts: untyped`

850

851 - `usage: BatchUsage`

852

853 Represents token usage details including input tokens, output tokens, a

854 breakdown of output tokens, and the total tokens used. Only populated on

855 batches created after September 7, 2025.

856

857 - `input_tokens: Integer`

858

859 The number of input tokens.

860

861 - `input_tokens_details: InputTokensDetails{ cached_tokens}`

862

863 A detailed breakdown of the input tokens.

864

865 - `cached_tokens: Integer`

866

867 The number of tokens that were retrieved from the cache. [More on

868 prompt caching](https://platform.openai.com/docs/guides/prompt-caching).

869

870 - `output_tokens: Integer`

871

872 The number of output tokens.

873

874 - `output_tokens_details: OutputTokensDetails{ reasoning_tokens}`

875

876 A detailed breakdown of the output tokens.

877

878 - `reasoning_tokens: Integer`

879

880 The number of reasoning tokens.

881

882 - `total_tokens: Integer`

883

884 The total number of tokens used.

885

886### Example

887

888```ruby

889require "openai"

890

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

892

893page = openai.batches.list

894

895puts(page)

896```

897

898#### Response

899

900```json

901{

902 "data": [

903 {

904 "id": "id",

905 "completion_window": "completion_window",

906 "created_at": 0,

907 "endpoint": "endpoint",

908 "input_file_id": "input_file_id",

909 "object": "batch",

910 "status": "validating",

911 "cancelled_at": 0,

912 "cancelling_at": 0,

913 "completed_at": 0,

914 "error_file_id": "error_file_id",

915 "errors": {

916 "data": [

917 {}

918 ],

919 "object": "object"

920 },

921 "expired_at": 0,

922 "expires_at": 0,

923 "failed_at": 0,

924 "finalizing_at": 0,

925 "in_progress_at": 0,

926 "metadata": {

927 "foo": "string"

928 },

929 "model": "model",

930 "output_file_id": "output_file_id",

931 "request_counts": {},

932 "usage": {

933 "input_tokens": 0,

934 "input_tokens_details": {

935 "cached_tokens": 0

936 },

937 "output_tokens": 0,

938 "output_tokens_details": {

939 "reasoning_tokens": 0

940 },

941 "total_tokens": 0

942 }

943 }

944 ],

945 "has_more": true,

946 "object": "list",

947 "first_id": "batch_abc123",

948 "last_id": "batch_abc456"

949}

950```

951

952## Domain Types

953

954### Batch

955

956- `class Batch`

957

958 - `id: String`

959

960 - `completion_window: String`

961

962 The time frame within which the batch should be processed.

963

964 - `created_at: Integer`

965

966 The Unix timestamp (in seconds) for when the batch was created.

967

968 - `endpoint: String`

969

970 The OpenAI API endpoint used by the batch.

971

972 - `input_file_id: String`

973

974 The ID of the input file for the batch.

975

976 - `object: :batch`

977

978 The object type, which is always `batch`.

979

980 - `:batch`

981

982 - `status: :validating | :failed | :in_progress | 5 more`

983

984 The current status of the batch.

985

986 - `:validating`

987

988 - `:failed`

989

990 - `:in_progress`

991

992 - `:finalizing`

993

994 - `:completed`

995

996 - `:expired`

997

998 - `:cancelling`

999

1000 - `:cancelled`

1001

1002 - `cancelled_at: Integer`

1003

1004 The Unix timestamp (in seconds) for when the batch was cancelled.

1005

1006 - `cancelling_at: Integer`

1007

1008 The Unix timestamp (in seconds) for when the batch started cancelling.

1009

1010 - `completed_at: Integer`

1011

1012 The Unix timestamp (in seconds) for when the batch was completed.

1013

1014 - `error_file_id: String`

1015

1016 The ID of the file containing the outputs of requests with errors.

1017

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

1019

1020 - `data: Array[untyped]`

1021

1022 - `object: String`

1023

1024 The object type, which is always `list`.

1025

1026 - `expired_at: Integer`

1027

1028 The Unix timestamp (in seconds) for when the batch expired.

1029

1030 - `expires_at: Integer`

1031

1032 The Unix timestamp (in seconds) for when the batch will expire.

1033

1034 - `failed_at: Integer`

1035

1036 The Unix timestamp (in seconds) for when the batch failed.

1037

1038 - `finalizing_at: Integer`

1039

1040 The Unix timestamp (in seconds) for when the batch started finalizing.

1041

1042 - `in_progress_at: Integer`

1043

1044 The Unix timestamp (in seconds) for when the batch started processing.

1045

1046 - `metadata: Metadata`

1047

1048 Set of 16 key-value pairs that can be attached to an object. This can be

1049 useful for storing additional information about the object in a structured

1050 format, and querying for objects via API or the dashboard.

1051

1052 Keys are strings with a maximum length of 64 characters. Values are strings

1053 with a maximum length of 512 characters.

1054

1055 - `model: String`

1056

1057 Model ID used to process the batch, like `gpt-5-2025-08-07`. OpenAI

1058 offers a wide range of models with different capabilities, performance

1059 characteristics, and price points. Refer to the [model

1060 guide](https://platform.openai.com/docs/models) to browse and compare available models.

1061

1062 - `output_file_id: String`

1063

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

1065

1066 - `request_counts: untyped`

1067

1068 - `usage: BatchUsage`

1069

1070 Represents token usage details including input tokens, output tokens, a

1071 breakdown of output tokens, and the total tokens used. Only populated on

1072 batches created after September 7, 2025.

1073

1074 - `input_tokens: Integer`

1075

1076 The number of input tokens.

1077

1078 - `input_tokens_details: InputTokensDetails{ cached_tokens}`

1079

1080 A detailed breakdown of the input tokens.

1081

1082 - `cached_tokens: Integer`

1083

1084 The number of tokens that were retrieved from the cache. [More on

1085 prompt caching](https://platform.openai.com/docs/guides/prompt-caching).

1086

1087 - `output_tokens: Integer`

1088

1089 The number of output tokens.

1090

1091 - `output_tokens_details: OutputTokensDetails{ reasoning_tokens}`

1092

1093 A detailed breakdown of the output tokens.

1094

1095 - `reasoning_tokens: Integer`

1096

1097 The number of reasoning tokens.

1098

1099 - `total_tokens: Integer`

1100

1101 The total number of tokens used.

1102

1103### Batch Error

1104

1105- `BatchError = untyped`

1106

1107### Batch Request Counts

1108

1109- `BatchRequestCounts = untyped`

1110

1111### Batch Usage

1112

1113- `class BatchUsage`

1114

1115 Represents token usage details including input tokens, output tokens, a

1116 breakdown of output tokens, and the total tokens used. Only populated on

1117 batches created after September 7, 2025.

1118

1119 - `input_tokens: Integer`

1120

1121 The number of input tokens.

1122

1123 - `input_tokens_details: InputTokensDetails{ cached_tokens}`

1124

1125 A detailed breakdown of the input tokens.

1126

1127 - `cached_tokens: Integer`

1128

1129 The number of tokens that were retrieved from the cache. [More on

1130 prompt caching](https://platform.openai.com/docs/guides/prompt-caching).

1131

1132 - `output_tokens: Integer`

1133

1134 The number of output tokens.

1135

1136 - `output_tokens_details: OutputTokensDetails{ reasoning_tokens}`

1137

1138 A detailed breakdown of the output tokens.

1139

1140 - `reasoning_tokens: Integer`

1141

1142 The number of reasoning tokens.

1143

1144 - `total_tokens: Integer`

1145

1146 The total number of tokens used.

ruby/resources/batches/index.md 2026-07-07 08:02 UTC to 2026-07-09 20: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