cli/resources/batches/methods/create/index.md +0 −280 deleted
File Deleted View Diff
1## Create batch
2
3`$ openai batches create`
4
5**post** `/batches`
6
7Creates and executes a batch from an uploaded file of requests
8
9### Parameters
10
11- `--completion-window: "24h"`
12
13 The time frame within which the batch should be processed. Currently only `24h` is supported.
14
15- `--endpoint: "/v1/responses" or "/v1/chat/completions" or "/v1/embeddings" or 5 more`
16
17 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.
18
19- `--input-file-id: string`
20
21 The ID of an uploaded file that contains requests for the new batch.
22
23 See [upload file](https://platform.openai.com/docs/api-reference/files/create) for how to upload a file.
24
25 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.
26
27- `--metadata: optional map[string]`
28
29 Set of 16 key-value pairs that can be attached to an object. This can be
30 useful for storing additional information about the object in a structured
31 format, and querying for objects via API or the dashboard.
32
33 Keys are strings with a maximum length of 64 characters. Values are strings
34 with a maximum length of 512 characters.
35
36- `--output-expires-after: optional object { anchor, seconds }`
37
38 The expiration policy for the output and/or error file that are generated for a batch.
39
40### Returns
41
42- `batch: object { id, completion_window, created_at, 19 more }`
43
44 - `id: string`
45
46 - `completion_window: string`
47
48 The time frame within which the batch should be processed.
49
50 - `created_at: number`
51
52 The Unix timestamp (in seconds) for when the batch was created.
53
54 - `endpoint: string`
55
56 The OpenAI API endpoint used by the batch.
57
58 - `input_file_id: string`
59
60 The ID of the input file for the batch.
61
62 - `object: "batch"`
63
64 The object type, which is always `batch`.
65
66 - `status: "validating" or "failed" or "in_progress" or 5 more`
67
68 The current status of the batch.
69
70 - `"validating"`
71
72 - `"failed"`
73
74 - `"in_progress"`
75
76 - `"finalizing"`
77
78 - `"completed"`
79
80 - `"expired"`
81
82 - `"cancelling"`
83
84 - `"cancelled"`
85
86 - `cancelled_at: optional number`
87
88 The Unix timestamp (in seconds) for when the batch was cancelled.
89
90 - `cancelling_at: optional number`
91
92 The Unix timestamp (in seconds) for when the batch started cancelling.
93
94 - `completed_at: optional number`
95
96 The Unix timestamp (in seconds) for when the batch was completed.
97
98 - `error_file_id: optional string`
99
100 The ID of the file containing the outputs of requests with errors.
101
102 - `errors: optional object { data, object }`
103
104 - `data: optional array of BatchError`
105
106 - `code: optional string`
107
108 An error code identifying the error type.
109
110 - `line: optional number`
111
112 The line number of the input file where the error occurred, if applicable.
113
114 - `message: optional string`
115
116 A human-readable message providing more details about the error.
117
118 - `param: optional string`
119
120 The name of the parameter that caused the error, if applicable.
121
122 - `object: optional string`
123
124 The object type, which is always `list`.
125
126 - `expired_at: optional number`
127
128 The Unix timestamp (in seconds) for when the batch expired.
129
130 - `expires_at: optional number`
131
132 The Unix timestamp (in seconds) for when the batch will expire.
133
134 - `failed_at: optional number`
135
136 The Unix timestamp (in seconds) for when the batch failed.
137
138 - `finalizing_at: optional number`
139
140 The Unix timestamp (in seconds) for when the batch started finalizing.
141
142 - `in_progress_at: optional number`
143
144 The Unix timestamp (in seconds) for when the batch started processing.
145
146 - `metadata: optional map[string]`
147
148 Set of 16 key-value pairs that can be attached to an object. This can be
149 useful for storing additional information about the object in a structured
150 format, and querying for objects via API or the dashboard.
151
152 Keys are strings with a maximum length of 64 characters. Values are strings
153 with a maximum length of 512 characters.
154
155 - `model: optional string`
156
157 Model ID used to process the batch, like `gpt-5-2025-08-07`. OpenAI
158 offers a wide range of models with different capabilities, performance
159 characteristics, and price points. Refer to the [model
160 guide](https://platform.openai.com/docs/models) to browse and compare available models.
161
162 - `output_file_id: optional string`
163
164 The ID of the file containing the outputs of successfully executed requests.
165
166 - `request_counts: optional object { completed, failed, total }`
167
168 The request counts for different statuses within the batch.
169
170 - `completed: number`
171
172 Number of requests that have been completed successfully.
173
174 - `failed: number`
175
176 Number of requests that have failed.
177
178 - `total: number`
179
180 Total number of requests in the batch.
181
182 - `usage: optional object { input_tokens, input_tokens_details, output_tokens, 2 more }`
183
184 Represents token usage details including input tokens, output tokens, a
185 breakdown of output tokens, and the total tokens used. Only populated on
186 batches created after September 7, 2025.
187
188 - `input_tokens: number`
189
190 The number of input tokens.
191
192 - `input_tokens_details: object { cached_tokens }`
193
194 A detailed breakdown of the input tokens.
195
196 - `cached_tokens: number`
197
198 The number of tokens that were retrieved from the cache. [More on
199 prompt caching](https://platform.openai.com/docs/guides/prompt-caching).
200
201 - `output_tokens: number`
202
203 The number of output tokens.
204
205 - `output_tokens_details: object { reasoning_tokens }`
206
207 A detailed breakdown of the output tokens.
208
209 - `reasoning_tokens: number`
210
211 The number of reasoning tokens.
212
213 - `total_tokens: number`
214
215 The total number of tokens used.
216
217### Example
218
219```cli
220openai batches create \
221 --api-key 'My API Key' \
222 --completion-window 24h \
223 --endpoint /v1/responses \
224 --input-file-id input_file_id
225```
226
227#### Response
228
229```json
230{
231 "id": "id",
232 "completion_window": "completion_window",
233 "created_at": 0,
234 "endpoint": "endpoint",
235 "input_file_id": "input_file_id",
236 "object": "batch",
237 "status": "validating",
238 "cancelled_at": 0,
239 "cancelling_at": 0,
240 "completed_at": 0,
241 "error_file_id": "error_file_id",
242 "errors": {
243 "data": [
244 {
245 "code": "code",
246 "line": 0,
247 "message": "message",
248 "param": "param"
249 }
250 ],
251 "object": "object"
252 },
253 "expired_at": 0,
254 "expires_at": 0,
255 "failed_at": 0,
256 "finalizing_at": 0,
257 "in_progress_at": 0,
258 "metadata": {
259 "foo": "string"
260 },
261 "model": "model",
262 "output_file_id": "output_file_id",
263 "request_counts": {
264 "completed": 0,
265 "failed": 0,
266 "total": 0
267 },
268 "usage": {
269 "input_tokens": 0,
270 "input_tokens_details": {
271 "cached_tokens": 0
272 },
273 "output_tokens": 0,
274 "output_tokens_details": {
275 "reasoning_tokens": 0
276 },
277 "total_tokens": 0
278 }
279}
280```