ruby/resources/batches/index.md +0 −1362 deleted
File Deleted View Diff
1# Batches
2
3## Create batch
4
5`batches.create(**kwargs) -> Batch`
6
7**post** `/batches`
8
9Creates and executes a batch from an uploaded file of requests
10
11### Parameters
12
13- `completion_window: :"24h"`
14
15 The time frame within which the batch should be processed. Currently only `24h` is supported.
16
17 - `:"24h"`
18
19- `endpoint: :"/v1/responses" | :"/v1/chat/completions" | :"/v1/embeddings" | 5 more`
20
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.
22
23 - `:"/v1/responses"`
24
25 - `:"/v1/chat/completions"`
26
27 - `:"/v1/embeddings"`
28
29 - `:"/v1/completions"`
30
31 - `:"/v1/moderations"`
32
33 - `:"/v1/images/generations"`
34
35 - `:"/v1/images/edits"`
36
37 - `:"/v1/videos"`
38
39- `input_file_id: String`
40
41 The ID of an uploaded file that contains requests for the new batch.
42
43 See [upload file](https://platform.openai.com/docs/api-reference/files/create) for how to upload a file.
44
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.
46
47- `metadata: Metadata`
48
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.
52
53 Keys are strings with a maximum length of 64 characters. Values are strings
54 with a maximum length of 512 characters.
55
56- `output_expires_after: OutputExpiresAfter{ anchor, seconds}`
57
58 The expiration policy for the output and/or error file that are generated for a batch.
59
60 - `anchor: :created_at`
61
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.
63
64 - `:created_at`
65
66 - `seconds: Integer`
67
68 The number of seconds after the anchor time that the file will expire. Must be between 3600 (1 hour) and 2592000 (30 days).
69
70### Returns
71
72- `class Batch`
73
74 - `id: String`
75
76 - `completion_window: String`
77
78 The time frame within which the batch should be processed.
79
80 - `created_at: Integer`
81
82 The Unix timestamp (in seconds) for when the batch was created.
83
84 - `endpoint: String`
85
86 The OpenAI API endpoint used by the batch.
87
88 - `input_file_id: String`
89
90 The ID of the input file for the batch.
91
92 - `object: :batch`
93
94 The object type, which is always `batch`.
95
96 - `:batch`
97
98 - `status: :validating | :failed | :in_progress | 5 more`
99
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[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.
153
154 - `object: String`
155
156 The object type, which is always `list`.
157
158 - `expired_at: Integer`
159
160 The Unix timestamp (in seconds) for when the batch expired.
161
162 - `expires_at: Integer`
163
164 The Unix timestamp (in seconds) for when the batch will expire.
165
166 - `failed_at: Integer`
167
168 The Unix timestamp (in seconds) for when the batch failed.
169
170 - `finalizing_at: Integer`
171
172 The Unix timestamp (in seconds) for when the batch started finalizing.
173
174 - `in_progress_at: Integer`
175
176 The Unix timestamp (in seconds) for when the batch started processing.
177
178 - `metadata: Metadata`
179
180 Set of 16 key-value pairs that can be attached to an object. This can be
181 useful for storing additional information about the object in a structured
182 format, and querying for objects via API or the dashboard.
183
184 Keys are strings with a maximum length of 64 characters. Values are strings
185 with a maximum length of 512 characters.
186
187 - `model: String`
188
189 Model ID used to process the batch, like `gpt-5-2025-08-07`. OpenAI
190 offers a wide range of models with different capabilities, performance
191 characteristics, and price points. Refer to the [model
192 guide](https://platform.openai.com/docs/models) to browse and compare available models.
193
194 - `output_file_id: String`
195
196 The ID of the file containing the outputs of successfully executed requests.
197
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.
213
214 - `usage: BatchUsage`
215
216 Represents token usage details including input tokens, output tokens, a
217 breakdown of output tokens, and the total tokens used. Only populated on
218 batches created after September 7, 2025.
219
220 - `input_tokens: Integer`
221
222 The number of input tokens.
223
224 - `input_tokens_details: InputTokensDetails{ cached_tokens}`
225
226 A detailed breakdown of the input tokens.
227
228 - `cached_tokens: Integer`
229
230 The number of tokens that were retrieved from the cache. [More on
231 prompt caching](https://platform.openai.com/docs/guides/prompt-caching).
232
233 - `output_tokens: Integer`
234
235 The number of output tokens.
236
237 - `output_tokens_details: OutputTokensDetails{ reasoning_tokens}`
238
239 A detailed breakdown of the output tokens.
240
241 - `reasoning_tokens: Integer`
242
243 The number of reasoning tokens.
244
245 - `total_tokens: Integer`
246
247 The total number of tokens used.
248
249### Example
250
251```ruby
252require "openai"
253
254openai = OpenAI::Client.new(api_key: "My API Key")
255
256batch = openai.batches.create(
257 completion_window: :"24h",
258 endpoint: :"/v1/responses",
259 input_file_id: "input_file_id"
260)
261
262puts(batch)
263```
264
265#### Response
266
267```json
268{
269 "id": "id",
270 "completion_window": "completion_window",
271 "created_at": 0,
272 "endpoint": "endpoint",
273 "input_file_id": "input_file_id",
274 "object": "batch",
275 "status": "validating",
276 "cancelled_at": 0,
277 "cancelling_at": 0,
278 "completed_at": 0,
279 "error_file_id": "error_file_id",
280 "errors": {
281 "data": [
282 {
283 "code": "code",
284 "line": 0,
285 "message": "message",
286 "param": "param"
287 }
288 ],
289 "object": "object"
290 },
291 "expired_at": 0,
292 "expires_at": 0,
293 "failed_at": 0,
294 "finalizing_at": 0,
295 "in_progress_at": 0,
296 "metadata": {
297 "foo": "string"
298 },
299 "model": "model",
300 "output_file_id": "output_file_id",
301 "request_counts": {
302 "completed": 0,
303 "failed": 0,
304 "total": 0
305 },
306 "usage": {
307 "input_tokens": 0,
308 "input_tokens_details": {
309 "cached_tokens": 0
310 },
311 "output_tokens": 0,
312 "output_tokens_details": {
313 "reasoning_tokens": 0
314 },
315 "total_tokens": 0
316 }
317}
318```
319
320## Retrieve batch
321
322`batches.retrieve(batch_id) -> Batch`
323
324**get** `/batches/{batch_id}`
325
326Retrieves a batch.
327
328### Parameters
329
330- `batch_id: String`
331
332### Returns
333
334- `class Batch`
335
336 - `id: String`
337
338 - `completion_window: String`
339
340 The time frame within which the batch should be processed.
341
342 - `created_at: Integer`
343
344 The Unix timestamp (in seconds) for when the batch was created.
345
346 - `endpoint: String`
347
348 The OpenAI API endpoint used by the batch.
349
350 - `input_file_id: String`
351
352 The ID of the input file for the batch.
353
354 - `object: :batch`
355
356 The object type, which is always `batch`.
357
358 - `:batch`
359
360 - `status: :validating | :failed | :in_progress | 5 more`
361
362 The current status of the batch.
363
364 - `:validating`
365
366 - `:failed`
367
368 - `:in_progress`
369
370 - `:finalizing`
371
372 - `:completed`
373
374 - `:expired`
375
376 - `:cancelling`
377
378 - `:cancelled`
379
380 - `cancelled_at: Integer`
381
382 The Unix timestamp (in seconds) for when the batch was cancelled.
383
384 - `cancelling_at: Integer`
385
386 The Unix timestamp (in seconds) for when the batch started cancelling.
387
388 - `completed_at: Integer`
389
390 The Unix timestamp (in seconds) for when the batch was completed.
391
392 - `error_file_id: String`
393
394 The ID of the file containing the outputs of requests with errors.
395
396 - `errors: Errors{ data, object}`
397
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.
415
416 - `object: String`
417
418 The object type, which is always `list`.
419
420 - `expired_at: Integer`
421
422 The Unix timestamp (in seconds) for when the batch expired.
423
424 - `expires_at: Integer`
425
426 The Unix timestamp (in seconds) for when the batch will expire.
427
428 - `failed_at: Integer`
429
430 The Unix timestamp (in seconds) for when the batch failed.
431
432 - `finalizing_at: Integer`
433
434 The Unix timestamp (in seconds) for when the batch started finalizing.
435
436 - `in_progress_at: Integer`
437
438 The Unix timestamp (in seconds) for when the batch started processing.
439
440 - `metadata: Metadata`
441
442 Set of 16 key-value pairs that can be attached to an object. This can be
443 useful for storing additional information about the object in a structured
444 format, and querying for objects via API or the dashboard.
445
446 Keys are strings with a maximum length of 64 characters. Values are strings
447 with a maximum length of 512 characters.
448
449 - `model: String`
450
451 Model ID used to process the batch, like `gpt-5-2025-08-07`. OpenAI
452 offers a wide range of models with different capabilities, performance
453 characteristics, and price points. Refer to the [model
454 guide](https://platform.openai.com/docs/models) to browse and compare available models.
455
456 - `output_file_id: String`
457
458 The ID of the file containing the outputs of successfully executed requests.
459
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.
475
476 - `usage: BatchUsage`
477
478 Represents token usage details including input tokens, output tokens, a
479 breakdown of output tokens, and the total tokens used. Only populated on
480 batches created after September 7, 2025.
481
482 - `input_tokens: Integer`
483
484 The number of input tokens.
485
486 - `input_tokens_details: InputTokensDetails{ cached_tokens}`
487
488 A detailed breakdown of the input tokens.
489
490 - `cached_tokens: Integer`
491
492 The number of tokens that were retrieved from the cache. [More on
493 prompt caching](https://platform.openai.com/docs/guides/prompt-caching).
494
495 - `output_tokens: Integer`
496
497 The number of output tokens.
498
499 - `output_tokens_details: OutputTokensDetails{ reasoning_tokens}`
500
501 A detailed breakdown of the output tokens.
502
503 - `reasoning_tokens: Integer`
504
505 The number of reasoning tokens.
506
507 - `total_tokens: Integer`
508
509 The total number of tokens used.
510
511### Example
512
513```ruby
514require "openai"
515
516openai = OpenAI::Client.new(api_key: "My API Key")
517
518batch = openai.batches.retrieve("batch_id")
519
520puts(batch)
521```
522
523#### Response
524
525```json
526{
527 "id": "id",
528 "completion_window": "completion_window",
529 "created_at": 0,
530 "endpoint": "endpoint",
531 "input_file_id": "input_file_id",
532 "object": "batch",
533 "status": "validating",
534 "cancelled_at": 0,
535 "cancelling_at": 0,
536 "completed_at": 0,
537 "error_file_id": "error_file_id",
538 "errors": {
539 "data": [
540 {
541 "code": "code",
542 "line": 0,
543 "message": "message",
544 "param": "param"
545 }
546 ],
547 "object": "object"
548 },
549 "expired_at": 0,
550 "expires_at": 0,
551 "failed_at": 0,
552 "finalizing_at": 0,
553 "in_progress_at": 0,
554 "metadata": {
555 "foo": "string"
556 },
557 "model": "model",
558 "output_file_id": "output_file_id",
559 "request_counts": {
560 "completed": 0,
561 "failed": 0,
562 "total": 0
563 },
564 "usage": {
565 "input_tokens": 0,
566 "input_tokens_details": {
567 "cached_tokens": 0
568 },
569 "output_tokens": 0,
570 "output_tokens_details": {
571 "reasoning_tokens": 0
572 },
573 "total_tokens": 0
574 }
575}
576```
577
578## Cancel batch
579
580`batches.cancel(batch_id) -> Batch`
581
582**post** `/batches/{batch_id}/cancel`
583
584Cancels 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.
585
586### Parameters
587
588- `batch_id: String`
589
590### Returns
591
592- `class Batch`
593
594 - `id: String`
595
596 - `completion_window: String`
597
598 The time frame within which the batch should be processed.
599
600 - `created_at: Integer`
601
602 The Unix timestamp (in seconds) for when the batch was created.
603
604 - `endpoint: String`
605
606 The OpenAI API endpoint used by the batch.
607
608 - `input_file_id: String`
609
610 The ID of the input file for the batch.
611
612 - `object: :batch`
613
614 The object type, which is always `batch`.
615
616 - `:batch`
617
618 - `status: :validating | :failed | :in_progress | 5 more`
619
620 The current status of the batch.
621
622 - `:validating`
623
624 - `:failed`
625
626 - `:in_progress`
627
628 - `:finalizing`
629
630 - `:completed`
631
632 - `:expired`
633
634 - `:cancelling`
635
636 - `:cancelled`
637
638 - `cancelled_at: Integer`
639
640 The Unix timestamp (in seconds) for when the batch was cancelled.
641
642 - `cancelling_at: Integer`
643
644 The Unix timestamp (in seconds) for when the batch started cancelling.
645
646 - `completed_at: Integer`
647
648 The Unix timestamp (in seconds) for when the batch was completed.
649
650 - `error_file_id: String`
651
652 The ID of the file containing the outputs of requests with errors.
653
654 - `errors: Errors{ data, object}`
655
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.
673
674 - `object: String`
675
676 The object type, which is always `list`.
677
678 - `expired_at: Integer`
679
680 The Unix timestamp (in seconds) for when the batch expired.
681
682 - `expires_at: Integer`
683
684 The Unix timestamp (in seconds) for when the batch will expire.
685
686 - `failed_at: Integer`
687
688 The Unix timestamp (in seconds) for when the batch failed.
689
690 - `finalizing_at: Integer`
691
692 The Unix timestamp (in seconds) for when the batch started finalizing.
693
694 - `in_progress_at: Integer`
695
696 The Unix timestamp (in seconds) for when the batch started processing.
697
698 - `metadata: Metadata`
699
700 Set of 16 key-value pairs that can be attached to an object. This can be
701 useful for storing additional information about the object in a structured
702 format, and querying for objects via API or the dashboard.
703
704 Keys are strings with a maximum length of 64 characters. Values are strings
705 with a maximum length of 512 characters.
706
707 - `model: String`
708
709 Model ID used to process the batch, like `gpt-5-2025-08-07`. OpenAI
710 offers a wide range of models with different capabilities, performance
711 characteristics, and price points. Refer to the [model
712 guide](https://platform.openai.com/docs/models) to browse and compare available models.
713
714 - `output_file_id: String`
715
716 The ID of the file containing the outputs of successfully executed requests.
717
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.
733
734 - `usage: BatchUsage`
735
736 Represents token usage details including input tokens, output tokens, a
737 breakdown of output tokens, and the total tokens used. Only populated on
738 batches created after September 7, 2025.
739
740 - `input_tokens: Integer`
741
742 The number of input tokens.
743
744 - `input_tokens_details: InputTokensDetails{ cached_tokens}`
745
746 A detailed breakdown of the input tokens.
747
748 - `cached_tokens: Integer`
749
750 The number of tokens that were retrieved from the cache. [More on
751 prompt caching](https://platform.openai.com/docs/guides/prompt-caching).
752
753 - `output_tokens: Integer`
754
755 The number of output tokens.
756
757 - `output_tokens_details: OutputTokensDetails{ reasoning_tokens}`
758
759 A detailed breakdown of the output tokens.
760
761 - `reasoning_tokens: Integer`
762
763 The number of reasoning tokens.
764
765 - `total_tokens: Integer`
766
767 The total number of tokens used.
768
769### Example
770
771```ruby
772require "openai"
773
774openai = OpenAI::Client.new(api_key: "My API Key")
775
776batch = openai.batches.cancel("batch_id")
777
778puts(batch)
779```
780
781#### Response
782
783```json
784{
785 "id": "id",
786 "completion_window": "completion_window",
787 "created_at": 0,
788 "endpoint": "endpoint",
789 "input_file_id": "input_file_id",
790 "object": "batch",
791 "status": "validating",
792 "cancelled_at": 0,
793 "cancelling_at": 0,
794 "completed_at": 0,
795 "error_file_id": "error_file_id",
796 "errors": {
797 "data": [
798 {
799 "code": "code",
800 "line": 0,
801 "message": "message",
802 "param": "param"
803 }
804 ],
805 "object": "object"
806 },
807 "expired_at": 0,
808 "expires_at": 0,
809 "failed_at": 0,
810 "finalizing_at": 0,
811 "in_progress_at": 0,
812 "metadata": {
813 "foo": "string"
814 },
815 "model": "model",
816 "output_file_id": "output_file_id",
817 "request_counts": {
818 "completed": 0,
819 "failed": 0,
820 "total": 0
821 },
822 "usage": {
823 "input_tokens": 0,
824 "input_tokens_details": {
825 "cached_tokens": 0
826 },
827 "output_tokens": 0,
828 "output_tokens_details": {
829 "reasoning_tokens": 0
830 },
831 "total_tokens": 0
832 }
833}
834```
835
836## List batches
837
838`batches.list(**kwargs) -> CursorPage<Batch>`
839
840**get** `/batches`
841
842List your organization's batches.
843
844### Parameters
845
846- `after: String`
847
848 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.
849
850- `limit: Integer`
851
852 A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20.
853
854### Returns
855
856- `class Batch`
857
858 - `id: String`
859
860 - `completion_window: String`
861
862 The time frame within which the batch should be processed.
863
864 - `created_at: Integer`
865
866 The Unix timestamp (in seconds) for when the batch was created.
867
868 - `endpoint: String`
869
870 The OpenAI API endpoint used by the batch.
871
872 - `input_file_id: String`
873
874 The ID of the input file for the batch.
875
876 - `object: :batch`
877
878 The object type, which is always `batch`.
879
880 - `:batch`
881
882 - `status: :validating | :failed | :in_progress | 5 more`
883
884 The current status of the batch.
885
886 - `:validating`
887
888 - `:failed`
889
890 - `:in_progress`
891
892 - `:finalizing`
893
894 - `:completed`
895
896 - `:expired`
897
898 - `:cancelling`
899
900 - `:cancelled`
901
902 - `cancelled_at: Integer`
903
904 The Unix timestamp (in seconds) for when the batch was cancelled.
905
906 - `cancelling_at: Integer`
907
908 The Unix timestamp (in seconds) for when the batch started cancelling.
909
910 - `completed_at: Integer`
911
912 The Unix timestamp (in seconds) for when the batch was completed.
913
914 - `error_file_id: String`
915
916 The ID of the file containing the outputs of requests with errors.
917
918 - `errors: Errors{ data, object}`
919
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.
937
938 - `object: String`
939
940 The object type, which is always `list`.
941
942 - `expired_at: Integer`
943
944 The Unix timestamp (in seconds) for when the batch expired.
945
946 - `expires_at: Integer`
947
948 The Unix timestamp (in seconds) for when the batch will expire.
949
950 - `failed_at: Integer`
951
952 The Unix timestamp (in seconds) for when the batch failed.
953
954 - `finalizing_at: Integer`
955
956 The Unix timestamp (in seconds) for when the batch started finalizing.
957
958 - `in_progress_at: Integer`
959
960 The Unix timestamp (in seconds) for when the batch started processing.
961
962 - `metadata: Metadata`
963
964 Set of 16 key-value pairs that can be attached to an object. This can be
965 useful for storing additional information about the object in a structured
966 format, and querying for objects via API or the dashboard.
967
968 Keys are strings with a maximum length of 64 characters. Values are strings
969 with a maximum length of 512 characters.
970
971 - `model: String`
972
973 Model ID used to process the batch, like `gpt-5-2025-08-07`. OpenAI
974 offers a wide range of models with different capabilities, performance
975 characteristics, and price points. Refer to the [model
976 guide](https://platform.openai.com/docs/models) to browse and compare available models.
977
978 - `output_file_id: String`
979
980 The ID of the file containing the outputs of successfully executed requests.
981
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.
997
998 - `usage: BatchUsage`
999
1000 Represents token usage details including input tokens, output tokens, a
1001 breakdown of output tokens, and the total tokens used. Only populated on
1002 batches created after September 7, 2025.
1003
1004 - `input_tokens: Integer`
1005
1006 The number of input tokens.
1007
1008 - `input_tokens_details: InputTokensDetails{ cached_tokens}`
1009
1010 A detailed breakdown of the input tokens.
1011
1012 - `cached_tokens: Integer`
1013
1014 The number of tokens that were retrieved from the cache. [More on
1015 prompt caching](https://platform.openai.com/docs/guides/prompt-caching).
1016
1017 - `output_tokens: Integer`
1018
1019 The number of output tokens.
1020
1021 - `output_tokens_details: OutputTokensDetails{ reasoning_tokens}`
1022
1023 A detailed breakdown of the output tokens.
1024
1025 - `reasoning_tokens: Integer`
1026
1027 The number of reasoning tokens.
1028
1029 - `total_tokens: Integer`
1030
1031 The total number of tokens used.
1032
1033### Example
1034
1035```ruby
1036require "openai"
1037
1038openai = OpenAI::Client.new(api_key: "My API Key")
1039
1040page = openai.batches.list
1041
1042puts(page)
1043```
1044
1045#### Response
1046
1047```json
1048{
1049 "data": [
1050 {
1051 "id": "id",
1052 "completion_window": "completion_window",
1053 "created_at": 0,
1054 "endpoint": "endpoint",
1055 "input_file_id": "input_file_id",
1056 "object": "batch",
1057 "status": "validating",
1058 "cancelled_at": 0,
1059 "cancelling_at": 0,
1060 "completed_at": 0,
1061 "error_file_id": "error_file_id",
1062 "errors": {
1063 "data": [
1064 {
1065 "code": "code",
1066 "line": 0,
1067 "message": "message",
1068 "param": "param"
1069 }
1070 ],
1071 "object": "object"
1072 },
1073 "expired_at": 0,
1074 "expires_at": 0,
1075 "failed_at": 0,
1076 "finalizing_at": 0,
1077 "in_progress_at": 0,
1078 "metadata": {
1079 "foo": "string"
1080 },
1081 "model": "model",
1082 "output_file_id": "output_file_id",
1083 "request_counts": {
1084 "completed": 0,
1085 "failed": 0,
1086 "total": 0
1087 },
1088 "usage": {
1089 "input_tokens": 0,
1090 "input_tokens_details": {
1091 "cached_tokens": 0
1092 },
1093 "output_tokens": 0,
1094 "output_tokens_details": {
1095 "reasoning_tokens": 0
1096 },
1097 "total_tokens": 0
1098 }
1099 }
1100 ],
1101 "has_more": true,
1102 "object": "list",
1103 "first_id": "batch_abc123",
1104 "last_id": "batch_abc456"
1105}
1106```
1107
1108## Domain Types
1109
1110### Batch
1111
1112- `class Batch`
1113
1114 - `id: String`
1115
1116 - `completion_window: String`
1117
1118 The time frame within which the batch should be processed.
1119
1120 - `created_at: Integer`
1121
1122 The Unix timestamp (in seconds) for when the batch was created.
1123
1124 - `endpoint: String`
1125
1126 The OpenAI API endpoint used by the batch.
1127
1128 - `input_file_id: String`
1129
1130 The ID of the input file for the batch.
1131
1132 - `object: :batch`
1133
1134 The object type, which is always `batch`.
1135
1136 - `:batch`
1137
1138 - `status: :validating | :failed | :in_progress | 5 more`
1139
1140 The current status of the batch.
1141
1142 - `:validating`
1143
1144 - `:failed`
1145
1146 - `:in_progress`
1147
1148 - `:finalizing`
1149
1150 - `:completed`
1151
1152 - `:expired`
1153
1154 - `:cancelling`
1155
1156 - `:cancelled`
1157
1158 - `cancelled_at: Integer`
1159
1160 The Unix timestamp (in seconds) for when the batch was cancelled.
1161
1162 - `cancelling_at: Integer`
1163
1164 The Unix timestamp (in seconds) for when the batch started cancelling.
1165
1166 - `completed_at: Integer`
1167
1168 The Unix timestamp (in seconds) for when the batch was completed.
1169
1170 - `error_file_id: String`
1171
1172 The ID of the file containing the outputs of requests with errors.
1173
1174 - `errors: Errors{ data, object}`
1175
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.
1193
1194 - `object: String`
1195
1196 The object type, which is always `list`.
1197
1198 - `expired_at: Integer`
1199
1200 The Unix timestamp (in seconds) for when the batch expired.
1201
1202 - `expires_at: Integer`
1203
1204 The Unix timestamp (in seconds) for when the batch will expire.
1205
1206 - `failed_at: Integer`
1207
1208 The Unix timestamp (in seconds) for when the batch failed.
1209
1210 - `finalizing_at: Integer`
1211
1212 The Unix timestamp (in seconds) for when the batch started finalizing.
1213
1214 - `in_progress_at: Integer`
1215
1216 The Unix timestamp (in seconds) for when the batch started processing.
1217
1218 - `metadata: Metadata`
1219
1220 Set of 16 key-value pairs that can be attached to an object. This can be
1221 useful for storing additional information about the object in a structured
1222 format, and querying for objects via API or the dashboard.
1223
1224 Keys are strings with a maximum length of 64 characters. Values are strings
1225 with a maximum length of 512 characters.
1226
1227 - `model: String`
1228
1229 Model ID used to process the batch, like `gpt-5-2025-08-07`. OpenAI
1230 offers a wide range of models with different capabilities, performance
1231 characteristics, and price points. Refer to the [model
1232 guide](https://platform.openai.com/docs/models) to browse and compare available models.
1233
1234 - `output_file_id: String`
1235
1236 The ID of the file containing the outputs of successfully executed requests.
1237
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.
1253
1254 - `usage: BatchUsage`
1255
1256 Represents token usage details including input tokens, output tokens, a
1257 breakdown of output tokens, and the total tokens used. Only populated on
1258 batches created after September 7, 2025.
1259
1260 - `input_tokens: Integer`
1261
1262 The number of input tokens.
1263
1264 - `input_tokens_details: InputTokensDetails{ cached_tokens}`
1265
1266 A detailed breakdown of the input tokens.
1267
1268 - `cached_tokens: Integer`
1269
1270 The number of tokens that were retrieved from the cache. [More on
1271 prompt caching](https://platform.openai.com/docs/guides/prompt-caching).
1272
1273 - `output_tokens: Integer`
1274
1275 The number of output tokens.
1276
1277 - `output_tokens_details: OutputTokensDetails{ reasoning_tokens}`
1278
1279 A detailed breakdown of the output tokens.
1280
1281 - `reasoning_tokens: Integer`
1282
1283 The number of reasoning tokens.
1284
1285 - `total_tokens: Integer`
1286
1287 The total number of tokens used.
1288
1289### Batch Error
1290
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.
1308
1309### Batch Request Counts
1310
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.
1326
1327### Batch Usage
1328
1329- `class BatchUsage`
1330
1331 Represents token usage details including input tokens, output tokens, a
1332 breakdown of output tokens, and the total tokens used. Only populated on
1333 batches created after September 7, 2025.
1334
1335 - `input_tokens: Integer`
1336
1337 The number of input tokens.
1338
1339 - `input_tokens_details: InputTokensDetails{ cached_tokens}`
1340
1341 A detailed breakdown of the input tokens.
1342
1343 - `cached_tokens: Integer`
1344
1345 The number of tokens that were retrieved from the cache. [More on
1346 prompt caching](https://platform.openai.com/docs/guides/prompt-caching).
1347
1348 - `output_tokens: Integer`
1349
1350 The number of output tokens.
1351
1352 - `output_tokens_details: OutputTokensDetails{ reasoning_tokens}`
1353
1354 A detailed breakdown of the output tokens.
1355
1356 - `reasoning_tokens: Integer`
1357
1358 The number of reasoning tokens.
1359
1360 - `total_tokens: Integer`
1361
1362 The total number of tokens used.