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