ruby/resources/batches/methods/retrieve/index.md +0 −257 deleted
File Deleted View Diff
1## Retrieve batch
2
3`batches.retrieve(batch_id) -> Batch`
4
5**get** `/batches/{batch_id}`
6
7Retrieves a batch.
8
9### Parameters
10
11- `batch_id: String`
12
13### Returns
14
15- `class Batch`
16
17 - `id: String`
18
19 - `completion_window: String`
20
21 The time frame within which the batch should be processed.
22
23 - `created_at: Integer`
24
25 The Unix timestamp (in seconds) for when the batch was created.
26
27 - `endpoint: String`
28
29 The OpenAI API endpoint used by the batch.
30
31 - `input_file_id: String`
32
33 The ID of the input file for the batch.
34
35 - `object: :batch`
36
37 The object type, which is always `batch`.
38
39 - `:batch`
40
41 - `status: :validating | :failed | :in_progress | 5 more`
42
43 The current status of the batch.
44
45 - `:validating`
46
47 - `:failed`
48
49 - `:in_progress`
50
51 - `:finalizing`
52
53 - `:completed`
54
55 - `:expired`
56
57 - `:cancelling`
58
59 - `:cancelled`
60
61 - `cancelled_at: Integer`
62
63 The Unix timestamp (in seconds) for when the batch was cancelled.
64
65 - `cancelling_at: Integer`
66
67 The Unix timestamp (in seconds) for when the batch started cancelling.
68
69 - `completed_at: Integer`
70
71 The Unix timestamp (in seconds) for when the batch was completed.
72
73 - `error_file_id: String`
74
75 The ID of the file containing the outputs of requests with errors.
76
77 - `errors: Errors{ data, object}`
78
79 - `data: Array[BatchError]`
80
81 - `code: String`
82
83 An error code identifying the error type.
84
85 - `line: Integer`
86
87 The line number of the input file where the error occurred, if applicable.
88
89 - `message: String`
90
91 A human-readable message providing more details about the error.
92
93 - `param: String`
94
95 The name of the parameter that caused the error, if applicable.
96
97 - `object: String`
98
99 The object type, which is always `list`.
100
101 - `expired_at: Integer`
102
103 The Unix timestamp (in seconds) for when the batch expired.
104
105 - `expires_at: Integer`
106
107 The Unix timestamp (in seconds) for when the batch will expire.
108
109 - `failed_at: Integer`
110
111 The Unix timestamp (in seconds) for when the batch failed.
112
113 - `finalizing_at: Integer`
114
115 The Unix timestamp (in seconds) for when the batch started finalizing.
116
117 - `in_progress_at: Integer`
118
119 The Unix timestamp (in seconds) for when the batch started processing.
120
121 - `metadata: Metadata`
122
123 Set of 16 key-value pairs that can be attached to an object. This can be
124 useful for storing additional information about the object in a structured
125 format, and querying for objects via API or the dashboard.
126
127 Keys are strings with a maximum length of 64 characters. Values are strings
128 with a maximum length of 512 characters.
129
130 - `model: String`
131
132 Model ID used to process the batch, like `gpt-5-2025-08-07`. OpenAI
133 offers a wide range of models with different capabilities, performance
134 characteristics, and price points. Refer to the [model
135 guide](https://platform.openai.com/docs/models) to browse and compare available models.
136
137 - `output_file_id: String`
138
139 The ID of the file containing the outputs of successfully executed requests.
140
141 - `request_counts: BatchRequestCounts`
142
143 The request counts for different statuses within the batch.
144
145 - `completed: Integer`
146
147 Number of requests that have been completed successfully.
148
149 - `failed: Integer`
150
151 Number of requests that have failed.
152
153 - `total: Integer`
154
155 Total number of requests in the batch.
156
157 - `usage: BatchUsage`
158
159 Represents token usage details including input tokens, output tokens, a
160 breakdown of output tokens, and the total tokens used. Only populated on
161 batches created after September 7, 2025.
162
163 - `input_tokens: Integer`
164
165 The number of input tokens.
166
167 - `input_tokens_details: InputTokensDetails{ cached_tokens}`
168
169 A detailed breakdown of the input tokens.
170
171 - `cached_tokens: Integer`
172
173 The number of tokens that were retrieved from the cache. [More on
174 prompt caching](https://platform.openai.com/docs/guides/prompt-caching).
175
176 - `output_tokens: Integer`
177
178 The number of output tokens.
179
180 - `output_tokens_details: OutputTokensDetails{ reasoning_tokens}`
181
182 A detailed breakdown of the output tokens.
183
184 - `reasoning_tokens: Integer`
185
186 The number of reasoning tokens.
187
188 - `total_tokens: Integer`
189
190 The total number of tokens used.
191
192### Example
193
194```ruby
195require "openai"
196
197openai = OpenAI::Client.new(api_key: "My API Key")
198
199batch = openai.batches.retrieve("batch_id")
200
201puts(batch)
202```
203
204#### Response
205
206```json
207{
208 "id": "id",
209 "completion_window": "completion_window",
210 "created_at": 0,
211 "endpoint": "endpoint",
212 "input_file_id": "input_file_id",
213 "object": "batch",
214 "status": "validating",
215 "cancelled_at": 0,
216 "cancelling_at": 0,
217 "completed_at": 0,
218 "error_file_id": "error_file_id",
219 "errors": {
220 "data": [
221 {
222 "code": "code",
223 "line": 0,
224 "message": "message",
225 "param": "param"
226 }
227 ],
228 "object": "object"
229 },
230 "expired_at": 0,
231 "expires_at": 0,
232 "failed_at": 0,
233 "finalizing_at": 0,
234 "in_progress_at": 0,
235 "metadata": {
236 "foo": "string"
237 },
238 "model": "model",
239 "output_file_id": "output_file_id",
240 "request_counts": {
241 "completed": 0,
242 "failed": 0,
243 "total": 0
244 },
245 "usage": {
246 "input_tokens": 0,
247 "input_tokens_details": {
248 "cached_tokens": 0
249 },
250 "output_tokens": 0,
251 "output_tokens_details": {
252 "reasoning_tokens": 0
253 },
254 "total_tokens": 0
255 }
256}
257```