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