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