java/resources/batches/index.md +0 −1407 deleted
File Deleted View Diff
1# Batches
2
3## Create batch
4
5`Batch batches().create(BatchCreateParamsparams, RequestOptionsrequestOptions = RequestOptions.none())`
6
7**post** `/batches`
8
9Creates and executes a batch from an uploaded file of requests
10
11### Parameters
12
13- `BatchCreateParams params`
14
15 - `CompletionWindow completionWindow`
16
17 The time frame within which the batch should be processed. Currently only `24h` is supported.
18
19 - `_24H("24h")`
20
21 - `Endpoint endpoint`
22
23 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.
24
25 - `V1_RESPONSES("/v1/responses")`
26
27 - `V1_CHAT_COMPLETIONS("/v1/chat/completions")`
28
29 - `V1_EMBEDDINGS("/v1/embeddings")`
30
31 - `V1_COMPLETIONS("/v1/completions")`
32
33 - `V1_MODERATIONS("/v1/moderations")`
34
35 - `V1_IMAGES_GENERATIONS("/v1/images/generations")`
36
37 - `V1_IMAGES_EDITS("/v1/images/edits")`
38
39 - `V1_VIDEOS("/v1/videos")`
40
41 - `String inputFileId`
42
43 The ID of an uploaded file that contains requests for the new batch.
44
45 See [upload file](https://platform.openai.com/docs/api-reference/files/create) for how to upload a file.
46
47 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.
48
49 - `Optional<Metadata> metadata`
50
51 Set of 16 key-value pairs that can be attached to an object. This can be
52 useful for storing additional information about the object in a structured
53 format, and querying for objects via API or the dashboard.
54
55 Keys are strings with a maximum length of 64 characters. Values are strings
56 with a maximum length of 512 characters.
57
58 - `Optional<OutputExpiresAfter> outputExpiresAfter`
59
60 The expiration policy for the output and/or error file that are generated for a batch.
61
62 - `JsonValue; anchor "created_at"constant`
63
64 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.
65
66 - `CREATED_AT("created_at")`
67
68 - `long seconds`
69
70 The number of seconds after the anchor time that the file will expire. Must be between 3600 (1 hour) and 2592000 (30 days).
71
72### Returns
73
74- `class Batch:`
75
76 - `String id`
77
78 - `String completionWindow`
79
80 The time frame within which the batch should be processed.
81
82 - `long createdAt`
83
84 The Unix timestamp (in seconds) for when the batch was created.
85
86 - `String endpoint`
87
88 The OpenAI API endpoint used by the batch.
89
90 - `String inputFileId`
91
92 The ID of the input file for the batch.
93
94 - `JsonValue; object_ "batch"constant`
95
96 The object type, which is always `batch`.
97
98 - `BATCH("batch")`
99
100 - `Status status`
101
102 The current status of the batch.
103
104 - `VALIDATING("validating")`
105
106 - `FAILED("failed")`
107
108 - `IN_PROGRESS("in_progress")`
109
110 - `FINALIZING("finalizing")`
111
112 - `COMPLETED("completed")`
113
114 - `EXPIRED("expired")`
115
116 - `CANCELLING("cancelling")`
117
118 - `CANCELLED("cancelled")`
119
120 - `Optional<Long> cancelledAt`
121
122 The Unix timestamp (in seconds) for when the batch was cancelled.
123
124 - `Optional<Long> cancellingAt`
125
126 The Unix timestamp (in seconds) for when the batch started cancelling.
127
128 - `Optional<Long> completedAt`
129
130 The Unix timestamp (in seconds) for when the batch was completed.
131
132 - `Optional<String> errorFileId`
133
134 The ID of the file containing the outputs of requests with errors.
135
136 - `Optional<Errors> errors`
137
138 - `Optional<List<BatchError>> data`
139
140 - `Optional<String> code`
141
142 An error code identifying the error type.
143
144 - `Optional<Long> line`
145
146 The line number of the input file where the error occurred, if applicable.
147
148 - `Optional<String> message`
149
150 A human-readable message providing more details about the error.
151
152 - `Optional<String> param`
153
154 The name of the parameter that caused the error, if applicable.
155
156 - `Optional<String> object_`
157
158 The object type, which is always `list`.
159
160 - `Optional<Long> expiredAt`
161
162 The Unix timestamp (in seconds) for when the batch expired.
163
164 - `Optional<Long> expiresAt`
165
166 The Unix timestamp (in seconds) for when the batch will expire.
167
168 - `Optional<Long> failedAt`
169
170 The Unix timestamp (in seconds) for when the batch failed.
171
172 - `Optional<Long> finalizingAt`
173
174 The Unix timestamp (in seconds) for when the batch started finalizing.
175
176 - `Optional<Long> inProgressAt`
177
178 The Unix timestamp (in seconds) for when the batch started processing.
179
180 - `Optional<Metadata> metadata`
181
182 Set of 16 key-value pairs that can be attached to an object. This can be
183 useful for storing additional information about the object in a structured
184 format, and querying for objects via API or the dashboard.
185
186 Keys are strings with a maximum length of 64 characters. Values are strings
187 with a maximum length of 512 characters.
188
189 - `Optional<String> model`
190
191 Model ID used to process the batch, like `gpt-5-2025-08-07`. OpenAI
192 offers a wide range of models with different capabilities, performance
193 characteristics, and price points. Refer to the [model
194 guide](https://platform.openai.com/docs/models) to browse and compare available models.
195
196 - `Optional<String> outputFileId`
197
198 The ID of the file containing the outputs of successfully executed requests.
199
200 - `Optional<BatchRequestCounts> requestCounts`
201
202 The request counts for different statuses within the batch.
203
204 - `long completed`
205
206 Number of requests that have been completed successfully.
207
208 - `long failed`
209
210 Number of requests that have failed.
211
212 - `long total`
213
214 Total number of requests in the batch.
215
216 - `Optional<BatchUsage> usage`
217
218 Represents token usage details including input tokens, output tokens, a
219 breakdown of output tokens, and the total tokens used. Only populated on
220 batches created after September 7, 2025.
221
222 - `long inputTokens`
223
224 The number of input tokens.
225
226 - `InputTokensDetails inputTokensDetails`
227
228 A detailed breakdown of the input tokens.
229
230 - `long cachedTokens`
231
232 The number of tokens that were retrieved from the cache. [More on
233 prompt caching](https://platform.openai.com/docs/guides/prompt-caching).
234
235 - `long outputTokens`
236
237 The number of output tokens.
238
239 - `OutputTokensDetails outputTokensDetails`
240
241 A detailed breakdown of the output tokens.
242
243 - `long reasoningTokens`
244
245 The number of reasoning tokens.
246
247 - `long totalTokens`
248
249 The total number of tokens used.
250
251### Example
252
253```java
254package com.openai.example;
255
256import com.openai.client.OpenAIClient;
257import com.openai.client.okhttp.OpenAIOkHttpClient;
258import com.openai.models.batches.Batch;
259import com.openai.models.batches.BatchCreateParams;
260
261public final class Main {
262 private Main() {}
263
264 public static void main(String[] args) {
265 OpenAIClient client = OpenAIOkHttpClient.fromEnv();
266
267 BatchCreateParams params = BatchCreateParams.builder()
268 .completionWindow(BatchCreateParams.CompletionWindow._24H)
269 .endpoint(BatchCreateParams.Endpoint.V1_RESPONSES)
270 .inputFileId("input_file_id")
271 .build();
272 Batch batch = client.batches().create(params);
273 }
274}
275```
276
277#### Response
278
279```json
280{
281 "id": "id",
282 "completion_window": "completion_window",
283 "created_at": 0,
284 "endpoint": "endpoint",
285 "input_file_id": "input_file_id",
286 "object": "batch",
287 "status": "validating",
288 "cancelled_at": 0,
289 "cancelling_at": 0,
290 "completed_at": 0,
291 "error_file_id": "error_file_id",
292 "errors": {
293 "data": [
294 {
295 "code": "code",
296 "line": 0,
297 "message": "message",
298 "param": "param"
299 }
300 ],
301 "object": "object"
302 },
303 "expired_at": 0,
304 "expires_at": 0,
305 "failed_at": 0,
306 "finalizing_at": 0,
307 "in_progress_at": 0,
308 "metadata": {
309 "foo": "string"
310 },
311 "model": "model",
312 "output_file_id": "output_file_id",
313 "request_counts": {
314 "completed": 0,
315 "failed": 0,
316 "total": 0
317 },
318 "usage": {
319 "input_tokens": 0,
320 "input_tokens_details": {
321 "cached_tokens": 0
322 },
323 "output_tokens": 0,
324 "output_tokens_details": {
325 "reasoning_tokens": 0
326 },
327 "total_tokens": 0
328 }
329}
330```
331
332## Retrieve batch
333
334`Batch batches().retrieve(BatchRetrieveParamsparams = BatchRetrieveParams.none(), RequestOptionsrequestOptions = RequestOptions.none())`
335
336**get** `/batches/{batch_id}`
337
338Retrieves a batch.
339
340### Parameters
341
342- `BatchRetrieveParams params`
343
344 - `Optional<String> batchId`
345
346### Returns
347
348- `class Batch:`
349
350 - `String id`
351
352 - `String completionWindow`
353
354 The time frame within which the batch should be processed.
355
356 - `long createdAt`
357
358 The Unix timestamp (in seconds) for when the batch was created.
359
360 - `String endpoint`
361
362 The OpenAI API endpoint used by the batch.
363
364 - `String inputFileId`
365
366 The ID of the input file for the batch.
367
368 - `JsonValue; object_ "batch"constant`
369
370 The object type, which is always `batch`.
371
372 - `BATCH("batch")`
373
374 - `Status status`
375
376 The current status of the batch.
377
378 - `VALIDATING("validating")`
379
380 - `FAILED("failed")`
381
382 - `IN_PROGRESS("in_progress")`
383
384 - `FINALIZING("finalizing")`
385
386 - `COMPLETED("completed")`
387
388 - `EXPIRED("expired")`
389
390 - `CANCELLING("cancelling")`
391
392 - `CANCELLED("cancelled")`
393
394 - `Optional<Long> cancelledAt`
395
396 The Unix timestamp (in seconds) for when the batch was cancelled.
397
398 - `Optional<Long> cancellingAt`
399
400 The Unix timestamp (in seconds) for when the batch started cancelling.
401
402 - `Optional<Long> completedAt`
403
404 The Unix timestamp (in seconds) for when the batch was completed.
405
406 - `Optional<String> errorFileId`
407
408 The ID of the file containing the outputs of requests with errors.
409
410 - `Optional<Errors> errors`
411
412 - `Optional<List<BatchError>> data`
413
414 - `Optional<String> code`
415
416 An error code identifying the error type.
417
418 - `Optional<Long> line`
419
420 The line number of the input file where the error occurred, if applicable.
421
422 - `Optional<String> message`
423
424 A human-readable message providing more details about the error.
425
426 - `Optional<String> param`
427
428 The name of the parameter that caused the error, if applicable.
429
430 - `Optional<String> object_`
431
432 The object type, which is always `list`.
433
434 - `Optional<Long> expiredAt`
435
436 The Unix timestamp (in seconds) for when the batch expired.
437
438 - `Optional<Long> expiresAt`
439
440 The Unix timestamp (in seconds) for when the batch will expire.
441
442 - `Optional<Long> failedAt`
443
444 The Unix timestamp (in seconds) for when the batch failed.
445
446 - `Optional<Long> finalizingAt`
447
448 The Unix timestamp (in seconds) for when the batch started finalizing.
449
450 - `Optional<Long> inProgressAt`
451
452 The Unix timestamp (in seconds) for when the batch started processing.
453
454 - `Optional<Metadata> metadata`
455
456 Set of 16 key-value pairs that can be attached to an object. This can be
457 useful for storing additional information about the object in a structured
458 format, and querying for objects via API or the dashboard.
459
460 Keys are strings with a maximum length of 64 characters. Values are strings
461 with a maximum length of 512 characters.
462
463 - `Optional<String> model`
464
465 Model ID used to process the batch, like `gpt-5-2025-08-07`. OpenAI
466 offers a wide range of models with different capabilities, performance
467 characteristics, and price points. Refer to the [model
468 guide](https://platform.openai.com/docs/models) to browse and compare available models.
469
470 - `Optional<String> outputFileId`
471
472 The ID of the file containing the outputs of successfully executed requests.
473
474 - `Optional<BatchRequestCounts> requestCounts`
475
476 The request counts for different statuses within the batch.
477
478 - `long completed`
479
480 Number of requests that have been completed successfully.
481
482 - `long failed`
483
484 Number of requests that have failed.
485
486 - `long total`
487
488 Total number of requests in the batch.
489
490 - `Optional<BatchUsage> usage`
491
492 Represents token usage details including input tokens, output tokens, a
493 breakdown of output tokens, and the total tokens used. Only populated on
494 batches created after September 7, 2025.
495
496 - `long inputTokens`
497
498 The number of input tokens.
499
500 - `InputTokensDetails inputTokensDetails`
501
502 A detailed breakdown of the input tokens.
503
504 - `long cachedTokens`
505
506 The number of tokens that were retrieved from the cache. [More on
507 prompt caching](https://platform.openai.com/docs/guides/prompt-caching).
508
509 - `long outputTokens`
510
511 The number of output tokens.
512
513 - `OutputTokensDetails outputTokensDetails`
514
515 A detailed breakdown of the output tokens.
516
517 - `long reasoningTokens`
518
519 The number of reasoning tokens.
520
521 - `long totalTokens`
522
523 The total number of tokens used.
524
525### Example
526
527```java
528package com.openai.example;
529
530import com.openai.client.OpenAIClient;
531import com.openai.client.okhttp.OpenAIOkHttpClient;
532import com.openai.models.batches.Batch;
533import com.openai.models.batches.BatchRetrieveParams;
534
535public final class Main {
536 private Main() {}
537
538 public static void main(String[] args) {
539 OpenAIClient client = OpenAIOkHttpClient.fromEnv();
540
541 Batch batch = client.batches().retrieve("batch_id");
542 }
543}
544```
545
546#### Response
547
548```json
549{
550 "id": "id",
551 "completion_window": "completion_window",
552 "created_at": 0,
553 "endpoint": "endpoint",
554 "input_file_id": "input_file_id",
555 "object": "batch",
556 "status": "validating",
557 "cancelled_at": 0,
558 "cancelling_at": 0,
559 "completed_at": 0,
560 "error_file_id": "error_file_id",
561 "errors": {
562 "data": [
563 {
564 "code": "code",
565 "line": 0,
566 "message": "message",
567 "param": "param"
568 }
569 ],
570 "object": "object"
571 },
572 "expired_at": 0,
573 "expires_at": 0,
574 "failed_at": 0,
575 "finalizing_at": 0,
576 "in_progress_at": 0,
577 "metadata": {
578 "foo": "string"
579 },
580 "model": "model",
581 "output_file_id": "output_file_id",
582 "request_counts": {
583 "completed": 0,
584 "failed": 0,
585 "total": 0
586 },
587 "usage": {
588 "input_tokens": 0,
589 "input_tokens_details": {
590 "cached_tokens": 0
591 },
592 "output_tokens": 0,
593 "output_tokens_details": {
594 "reasoning_tokens": 0
595 },
596 "total_tokens": 0
597 }
598}
599```
600
601## Cancel batch
602
603`Batch batches().cancel(BatchCancelParamsparams = BatchCancelParams.none(), RequestOptionsrequestOptions = RequestOptions.none())`
604
605**post** `/batches/{batch_id}/cancel`
606
607Cancels 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.
608
609### Parameters
610
611- `BatchCancelParams params`
612
613 - `Optional<String> batchId`
614
615### Returns
616
617- `class Batch:`
618
619 - `String id`
620
621 - `String completionWindow`
622
623 The time frame within which the batch should be processed.
624
625 - `long createdAt`
626
627 The Unix timestamp (in seconds) for when the batch was created.
628
629 - `String endpoint`
630
631 The OpenAI API endpoint used by the batch.
632
633 - `String inputFileId`
634
635 The ID of the input file for the batch.
636
637 - `JsonValue; object_ "batch"constant`
638
639 The object type, which is always `batch`.
640
641 - `BATCH("batch")`
642
643 - `Status status`
644
645 The current status of the batch.
646
647 - `VALIDATING("validating")`
648
649 - `FAILED("failed")`
650
651 - `IN_PROGRESS("in_progress")`
652
653 - `FINALIZING("finalizing")`
654
655 - `COMPLETED("completed")`
656
657 - `EXPIRED("expired")`
658
659 - `CANCELLING("cancelling")`
660
661 - `CANCELLED("cancelled")`
662
663 - `Optional<Long> cancelledAt`
664
665 The Unix timestamp (in seconds) for when the batch was cancelled.
666
667 - `Optional<Long> cancellingAt`
668
669 The Unix timestamp (in seconds) for when the batch started cancelling.
670
671 - `Optional<Long> completedAt`
672
673 The Unix timestamp (in seconds) for when the batch was completed.
674
675 - `Optional<String> errorFileId`
676
677 The ID of the file containing the outputs of requests with errors.
678
679 - `Optional<Errors> errors`
680
681 - `Optional<List<BatchError>> data`
682
683 - `Optional<String> code`
684
685 An error code identifying the error type.
686
687 - `Optional<Long> line`
688
689 The line number of the input file where the error occurred, if applicable.
690
691 - `Optional<String> message`
692
693 A human-readable message providing more details about the error.
694
695 - `Optional<String> param`
696
697 The name of the parameter that caused the error, if applicable.
698
699 - `Optional<String> object_`
700
701 The object type, which is always `list`.
702
703 - `Optional<Long> expiredAt`
704
705 The Unix timestamp (in seconds) for when the batch expired.
706
707 - `Optional<Long> expiresAt`
708
709 The Unix timestamp (in seconds) for when the batch will expire.
710
711 - `Optional<Long> failedAt`
712
713 The Unix timestamp (in seconds) for when the batch failed.
714
715 - `Optional<Long> finalizingAt`
716
717 The Unix timestamp (in seconds) for when the batch started finalizing.
718
719 - `Optional<Long> inProgressAt`
720
721 The Unix timestamp (in seconds) for when the batch started processing.
722
723 - `Optional<Metadata> metadata`
724
725 Set of 16 key-value pairs that can be attached to an object. This can be
726 useful for storing additional information about the object in a structured
727 format, and querying for objects via API or the dashboard.
728
729 Keys are strings with a maximum length of 64 characters. Values are strings
730 with a maximum length of 512 characters.
731
732 - `Optional<String> model`
733
734 Model ID used to process the batch, like `gpt-5-2025-08-07`. OpenAI
735 offers a wide range of models with different capabilities, performance
736 characteristics, and price points. Refer to the [model
737 guide](https://platform.openai.com/docs/models) to browse and compare available models.
738
739 - `Optional<String> outputFileId`
740
741 The ID of the file containing the outputs of successfully executed requests.
742
743 - `Optional<BatchRequestCounts> requestCounts`
744
745 The request counts for different statuses within the batch.
746
747 - `long completed`
748
749 Number of requests that have been completed successfully.
750
751 - `long failed`
752
753 Number of requests that have failed.
754
755 - `long total`
756
757 Total number of requests in the batch.
758
759 - `Optional<BatchUsage> usage`
760
761 Represents token usage details including input tokens, output tokens, a
762 breakdown of output tokens, and the total tokens used. Only populated on
763 batches created after September 7, 2025.
764
765 - `long inputTokens`
766
767 The number of input tokens.
768
769 - `InputTokensDetails inputTokensDetails`
770
771 A detailed breakdown of the input tokens.
772
773 - `long cachedTokens`
774
775 The number of tokens that were retrieved from the cache. [More on
776 prompt caching](https://platform.openai.com/docs/guides/prompt-caching).
777
778 - `long outputTokens`
779
780 The number of output tokens.
781
782 - `OutputTokensDetails outputTokensDetails`
783
784 A detailed breakdown of the output tokens.
785
786 - `long reasoningTokens`
787
788 The number of reasoning tokens.
789
790 - `long totalTokens`
791
792 The total number of tokens used.
793
794### Example
795
796```java
797package com.openai.example;
798
799import com.openai.client.OpenAIClient;
800import com.openai.client.okhttp.OpenAIOkHttpClient;
801import com.openai.models.batches.Batch;
802import com.openai.models.batches.BatchCancelParams;
803
804public final class Main {
805 private Main() {}
806
807 public static void main(String[] args) {
808 OpenAIClient client = OpenAIOkHttpClient.fromEnv();
809
810 Batch batch = client.batches().cancel("batch_id");
811 }
812}
813```
814
815#### Response
816
817```json
818{
819 "id": "id",
820 "completion_window": "completion_window",
821 "created_at": 0,
822 "endpoint": "endpoint",
823 "input_file_id": "input_file_id",
824 "object": "batch",
825 "status": "validating",
826 "cancelled_at": 0,
827 "cancelling_at": 0,
828 "completed_at": 0,
829 "error_file_id": "error_file_id",
830 "errors": {
831 "data": [
832 {
833 "code": "code",
834 "line": 0,
835 "message": "message",
836 "param": "param"
837 }
838 ],
839 "object": "object"
840 },
841 "expired_at": 0,
842 "expires_at": 0,
843 "failed_at": 0,
844 "finalizing_at": 0,
845 "in_progress_at": 0,
846 "metadata": {
847 "foo": "string"
848 },
849 "model": "model",
850 "output_file_id": "output_file_id",
851 "request_counts": {
852 "completed": 0,
853 "failed": 0,
854 "total": 0
855 },
856 "usage": {
857 "input_tokens": 0,
858 "input_tokens_details": {
859 "cached_tokens": 0
860 },
861 "output_tokens": 0,
862 "output_tokens_details": {
863 "reasoning_tokens": 0
864 },
865 "total_tokens": 0
866 }
867}
868```
869
870## List batches
871
872`BatchListPage batches().list(BatchListParamsparams = BatchListParams.none(), RequestOptionsrequestOptions = RequestOptions.none())`
873
874**get** `/batches`
875
876List your organization's batches.
877
878### Parameters
879
880- `BatchListParams params`
881
882 - `Optional<String> after`
883
884 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.
885
886 - `Optional<Long> limit`
887
888 A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20.
889
890### Returns
891
892- `class Batch:`
893
894 - `String id`
895
896 - `String completionWindow`
897
898 The time frame within which the batch should be processed.
899
900 - `long createdAt`
901
902 The Unix timestamp (in seconds) for when the batch was created.
903
904 - `String endpoint`
905
906 The OpenAI API endpoint used by the batch.
907
908 - `String inputFileId`
909
910 The ID of the input file for the batch.
911
912 - `JsonValue; object_ "batch"constant`
913
914 The object type, which is always `batch`.
915
916 - `BATCH("batch")`
917
918 - `Status status`
919
920 The current status of the batch.
921
922 - `VALIDATING("validating")`
923
924 - `FAILED("failed")`
925
926 - `IN_PROGRESS("in_progress")`
927
928 - `FINALIZING("finalizing")`
929
930 - `COMPLETED("completed")`
931
932 - `EXPIRED("expired")`
933
934 - `CANCELLING("cancelling")`
935
936 - `CANCELLED("cancelled")`
937
938 - `Optional<Long> cancelledAt`
939
940 The Unix timestamp (in seconds) for when the batch was cancelled.
941
942 - `Optional<Long> cancellingAt`
943
944 The Unix timestamp (in seconds) for when the batch started cancelling.
945
946 - `Optional<Long> completedAt`
947
948 The Unix timestamp (in seconds) for when the batch was completed.
949
950 - `Optional<String> errorFileId`
951
952 The ID of the file containing the outputs of requests with errors.
953
954 - `Optional<Errors> errors`
955
956 - `Optional<List<BatchError>> data`
957
958 - `Optional<String> code`
959
960 An error code identifying the error type.
961
962 - `Optional<Long> line`
963
964 The line number of the input file where the error occurred, if applicable.
965
966 - `Optional<String> message`
967
968 A human-readable message providing more details about the error.
969
970 - `Optional<String> param`
971
972 The name of the parameter that caused the error, if applicable.
973
974 - `Optional<String> object_`
975
976 The object type, which is always `list`.
977
978 - `Optional<Long> expiredAt`
979
980 The Unix timestamp (in seconds) for when the batch expired.
981
982 - `Optional<Long> expiresAt`
983
984 The Unix timestamp (in seconds) for when the batch will expire.
985
986 - `Optional<Long> failedAt`
987
988 The Unix timestamp (in seconds) for when the batch failed.
989
990 - `Optional<Long> finalizingAt`
991
992 The Unix timestamp (in seconds) for when the batch started finalizing.
993
994 - `Optional<Long> inProgressAt`
995
996 The Unix timestamp (in seconds) for when the batch started processing.
997
998 - `Optional<Metadata> metadata`
999
1000 Set of 16 key-value pairs that can be attached to an object. This can be
1001 useful for storing additional information about the object in a structured
1002 format, and querying for objects via API or the dashboard.
1003
1004 Keys are strings with a maximum length of 64 characters. Values are strings
1005 with a maximum length of 512 characters.
1006
1007 - `Optional<String> model`
1008
1009 Model ID used to process the batch, like `gpt-5-2025-08-07`. OpenAI
1010 offers a wide range of models with different capabilities, performance
1011 characteristics, and price points. Refer to the [model
1012 guide](https://platform.openai.com/docs/models) to browse and compare available models.
1013
1014 - `Optional<String> outputFileId`
1015
1016 The ID of the file containing the outputs of successfully executed requests.
1017
1018 - `Optional<BatchRequestCounts> requestCounts`
1019
1020 The request counts for different statuses within the batch.
1021
1022 - `long completed`
1023
1024 Number of requests that have been completed successfully.
1025
1026 - `long failed`
1027
1028 Number of requests that have failed.
1029
1030 - `long total`
1031
1032 Total number of requests in the batch.
1033
1034 - `Optional<BatchUsage> usage`
1035
1036 Represents token usage details including input tokens, output tokens, a
1037 breakdown of output tokens, and the total tokens used. Only populated on
1038 batches created after September 7, 2025.
1039
1040 - `long inputTokens`
1041
1042 The number of input tokens.
1043
1044 - `InputTokensDetails inputTokensDetails`
1045
1046 A detailed breakdown of the input tokens.
1047
1048 - `long cachedTokens`
1049
1050 The number of tokens that were retrieved from the cache. [More on
1051 prompt caching](https://platform.openai.com/docs/guides/prompt-caching).
1052
1053 - `long outputTokens`
1054
1055 The number of output tokens.
1056
1057 - `OutputTokensDetails outputTokensDetails`
1058
1059 A detailed breakdown of the output tokens.
1060
1061 - `long reasoningTokens`
1062
1063 The number of reasoning tokens.
1064
1065 - `long totalTokens`
1066
1067 The total number of tokens used.
1068
1069### Example
1070
1071```java
1072package com.openai.example;
1073
1074import com.openai.client.OpenAIClient;
1075import com.openai.client.okhttp.OpenAIOkHttpClient;
1076import com.openai.models.batches.BatchListPage;
1077import com.openai.models.batches.BatchListParams;
1078
1079public final class Main {
1080 private Main() {}
1081
1082 public static void main(String[] args) {
1083 OpenAIClient client = OpenAIOkHttpClient.fromEnv();
1084
1085 BatchListPage page = client.batches().list();
1086 }
1087}
1088```
1089
1090#### Response
1091
1092```json
1093{
1094 "data": [
1095 {
1096 "id": "id",
1097 "completion_window": "completion_window",
1098 "created_at": 0,
1099 "endpoint": "endpoint",
1100 "input_file_id": "input_file_id",
1101 "object": "batch",
1102 "status": "validating",
1103 "cancelled_at": 0,
1104 "cancelling_at": 0,
1105 "completed_at": 0,
1106 "error_file_id": "error_file_id",
1107 "errors": {
1108 "data": [
1109 {
1110 "code": "code",
1111 "line": 0,
1112 "message": "message",
1113 "param": "param"
1114 }
1115 ],
1116 "object": "object"
1117 },
1118 "expired_at": 0,
1119 "expires_at": 0,
1120 "failed_at": 0,
1121 "finalizing_at": 0,
1122 "in_progress_at": 0,
1123 "metadata": {
1124 "foo": "string"
1125 },
1126 "model": "model",
1127 "output_file_id": "output_file_id",
1128 "request_counts": {
1129 "completed": 0,
1130 "failed": 0,
1131 "total": 0
1132 },
1133 "usage": {
1134 "input_tokens": 0,
1135 "input_tokens_details": {
1136 "cached_tokens": 0
1137 },
1138 "output_tokens": 0,
1139 "output_tokens_details": {
1140 "reasoning_tokens": 0
1141 },
1142 "total_tokens": 0
1143 }
1144 }
1145 ],
1146 "has_more": true,
1147 "object": "list",
1148 "first_id": "batch_abc123",
1149 "last_id": "batch_abc456"
1150}
1151```
1152
1153## Domain Types
1154
1155### Batch
1156
1157- `class Batch:`
1158
1159 - `String id`
1160
1161 - `String completionWindow`
1162
1163 The time frame within which the batch should be processed.
1164
1165 - `long createdAt`
1166
1167 The Unix timestamp (in seconds) for when the batch was created.
1168
1169 - `String endpoint`
1170
1171 The OpenAI API endpoint used by the batch.
1172
1173 - `String inputFileId`
1174
1175 The ID of the input file for the batch.
1176
1177 - `JsonValue; object_ "batch"constant`
1178
1179 The object type, which is always `batch`.
1180
1181 - `BATCH("batch")`
1182
1183 - `Status status`
1184
1185 The current status of the batch.
1186
1187 - `VALIDATING("validating")`
1188
1189 - `FAILED("failed")`
1190
1191 - `IN_PROGRESS("in_progress")`
1192
1193 - `FINALIZING("finalizing")`
1194
1195 - `COMPLETED("completed")`
1196
1197 - `EXPIRED("expired")`
1198
1199 - `CANCELLING("cancelling")`
1200
1201 - `CANCELLED("cancelled")`
1202
1203 - `Optional<Long> cancelledAt`
1204
1205 The Unix timestamp (in seconds) for when the batch was cancelled.
1206
1207 - `Optional<Long> cancellingAt`
1208
1209 The Unix timestamp (in seconds) for when the batch started cancelling.
1210
1211 - `Optional<Long> completedAt`
1212
1213 The Unix timestamp (in seconds) for when the batch was completed.
1214
1215 - `Optional<String> errorFileId`
1216
1217 The ID of the file containing the outputs of requests with errors.
1218
1219 - `Optional<Errors> errors`
1220
1221 - `Optional<List<BatchError>> data`
1222
1223 - `Optional<String> code`
1224
1225 An error code identifying the error type.
1226
1227 - `Optional<Long> line`
1228
1229 The line number of the input file where the error occurred, if applicable.
1230
1231 - `Optional<String> message`
1232
1233 A human-readable message providing more details about the error.
1234
1235 - `Optional<String> param`
1236
1237 The name of the parameter that caused the error, if applicable.
1238
1239 - `Optional<String> object_`
1240
1241 The object type, which is always `list`.
1242
1243 - `Optional<Long> expiredAt`
1244
1245 The Unix timestamp (in seconds) for when the batch expired.
1246
1247 - `Optional<Long> expiresAt`
1248
1249 The Unix timestamp (in seconds) for when the batch will expire.
1250
1251 - `Optional<Long> failedAt`
1252
1253 The Unix timestamp (in seconds) for when the batch failed.
1254
1255 - `Optional<Long> finalizingAt`
1256
1257 The Unix timestamp (in seconds) for when the batch started finalizing.
1258
1259 - `Optional<Long> inProgressAt`
1260
1261 The Unix timestamp (in seconds) for when the batch started processing.
1262
1263 - `Optional<Metadata> metadata`
1264
1265 Set of 16 key-value pairs that can be attached to an object. This can be
1266 useful for storing additional information about the object in a structured
1267 format, and querying for objects via API or the dashboard.
1268
1269 Keys are strings with a maximum length of 64 characters. Values are strings
1270 with a maximum length of 512 characters.
1271
1272 - `Optional<String> model`
1273
1274 Model ID used to process the batch, like `gpt-5-2025-08-07`. OpenAI
1275 offers a wide range of models with different capabilities, performance
1276 characteristics, and price points. Refer to the [model
1277 guide](https://platform.openai.com/docs/models) to browse and compare available models.
1278
1279 - `Optional<String> outputFileId`
1280
1281 The ID of the file containing the outputs of successfully executed requests.
1282
1283 - `Optional<BatchRequestCounts> requestCounts`
1284
1285 The request counts for different statuses within the batch.
1286
1287 - `long completed`
1288
1289 Number of requests that have been completed successfully.
1290
1291 - `long failed`
1292
1293 Number of requests that have failed.
1294
1295 - `long total`
1296
1297 Total number of requests in the batch.
1298
1299 - `Optional<BatchUsage> usage`
1300
1301 Represents token usage details including input tokens, output tokens, a
1302 breakdown of output tokens, and the total tokens used. Only populated on
1303 batches created after September 7, 2025.
1304
1305 - `long inputTokens`
1306
1307 The number of input tokens.
1308
1309 - `InputTokensDetails inputTokensDetails`
1310
1311 A detailed breakdown of the input tokens.
1312
1313 - `long cachedTokens`
1314
1315 The number of tokens that were retrieved from the cache. [More on
1316 prompt caching](https://platform.openai.com/docs/guides/prompt-caching).
1317
1318 - `long outputTokens`
1319
1320 The number of output tokens.
1321
1322 - `OutputTokensDetails outputTokensDetails`
1323
1324 A detailed breakdown of the output tokens.
1325
1326 - `long reasoningTokens`
1327
1328 The number of reasoning tokens.
1329
1330 - `long totalTokens`
1331
1332 The total number of tokens used.
1333
1334### Batch Error
1335
1336- `class BatchError:`
1337
1338 - `Optional<String> code`
1339
1340 An error code identifying the error type.
1341
1342 - `Optional<Long> line`
1343
1344 The line number of the input file where the error occurred, if applicable.
1345
1346 - `Optional<String> message`
1347
1348 A human-readable message providing more details about the error.
1349
1350 - `Optional<String> param`
1351
1352 The name of the parameter that caused the error, if applicable.
1353
1354### Batch Request Counts
1355
1356- `class BatchRequestCounts:`
1357
1358 The request counts for different statuses within the batch.
1359
1360 - `long completed`
1361
1362 Number of requests that have been completed successfully.
1363
1364 - `long failed`
1365
1366 Number of requests that have failed.
1367
1368 - `long total`
1369
1370 Total number of requests in the batch.
1371
1372### Batch Usage
1373
1374- `class BatchUsage:`
1375
1376 Represents token usage details including input tokens, output tokens, a
1377 breakdown of output tokens, and the total tokens used. Only populated on
1378 batches created after September 7, 2025.
1379
1380 - `long inputTokens`
1381
1382 The number of input tokens.
1383
1384 - `InputTokensDetails inputTokensDetails`
1385
1386 A detailed breakdown of the input tokens.
1387
1388 - `long cachedTokens`
1389
1390 The number of tokens that were retrieved from the cache. [More on
1391 prompt caching](https://platform.openai.com/docs/guides/prompt-caching).
1392
1393 - `long outputTokens`
1394
1395 The number of output tokens.
1396
1397 - `OutputTokensDetails outputTokensDetails`
1398
1399 A detailed breakdown of the output tokens.
1400
1401 - `long reasoningTokens`
1402
1403 The number of reasoning tokens.
1404
1405 - `long totalTokens`
1406
1407 The total number of tokens used.