python/resources/batches/methods/create/index.md +0 −364 deleted
File Deleted View Diff
1## Create batch
2
3`batches.create(BatchCreateParams**kwargs) -> Batch`
4
5**post** `/batches`
6
7Creates and executes a batch from an uploaded file of requests
8
9### Parameters
10
11- `completion_window: Literal["24h"]`
12
13 The time frame within which the batch should be processed. Currently only `24h` is supported.
14
15 - `"24h"`
16
17- `endpoint: Literal["/v1/responses", "/v1/chat/completions", "/v1/embeddings", 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 - `"/v1/responses"`
22
23 - `"/v1/chat/completions"`
24
25 - `"/v1/embeddings"`
26
27 - `"/v1/completions"`
28
29 - `"/v1/moderations"`
30
31 - `"/v1/images/generations"`
32
33 - `"/v1/images/edits"`
34
35 - `"/v1/videos"`
36
37- `input_file_id: str`
38
39 The ID of an uploaded file that contains requests for the new batch.
40
41 See [upload file](https://platform.openai.com/docs/api-reference/files/create) for how to upload a file.
42
43 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.
44
45- `metadata: Optional[Metadata]`
46
47 Set of 16 key-value pairs that can be attached to an object. This can be
48 useful for storing additional information about the object in a structured
49 format, and querying for objects via API or the dashboard.
50
51 Keys are strings with a maximum length of 64 characters. Values are strings
52 with a maximum length of 512 characters.
53
54- `output_expires_after: Optional[OutputExpiresAfter]`
55
56 The expiration policy for the output and/or error file that are generated for a batch.
57
58 - `anchor: Literal["created_at"]`
59
60 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.
61
62 - `"created_at"`
63
64 - `seconds: int`
65
66 The number of seconds after the anchor time that the file will expire. Must be between 3600 (1 hour) and 2592000 (30 days).
67
68### Returns
69
70- `class Batch: …`
71
72 - `id: str`
73
74 - `completion_window: str`
75
76 The time frame within which the batch should be processed.
77
78 - `created_at: int`
79
80 The Unix timestamp (in seconds) for when the batch was created.
81
82 - `endpoint: str`
83
84 The OpenAI API endpoint used by the batch.
85
86 - `input_file_id: str`
87
88 The ID of the input file for the batch.
89
90 - `object: Literal["batch"]`
91
92 The object type, which is always `batch`.
93
94 - `"batch"`
95
96 - `status: Literal["validating", "failed", "in_progress", 5 more]`
97
98 The current status of the batch.
99
100 - `"validating"`
101
102 - `"failed"`
103
104 - `"in_progress"`
105
106 - `"finalizing"`
107
108 - `"completed"`
109
110 - `"expired"`
111
112 - `"cancelling"`
113
114 - `"cancelled"`
115
116 - `cancelled_at: Optional[int]`
117
118 The Unix timestamp (in seconds) for when the batch was cancelled.
119
120 - `cancelling_at: Optional[int]`
121
122 The Unix timestamp (in seconds) for when the batch started cancelling.
123
124 - `completed_at: Optional[int]`
125
126 The Unix timestamp (in seconds) for when the batch was completed.
127
128 - `error_file_id: Optional[str]`
129
130 The ID of the file containing the outputs of requests with errors.
131
132 - `errors: Optional[Errors]`
133
134 - `data: Optional[List[BatchError]]`
135
136 - `code: Optional[str]`
137
138 An error code identifying the error type.
139
140 - `line: Optional[int]`
141
142 The line number of the input file where the error occurred, if applicable.
143
144 - `message: Optional[str]`
145
146 A human-readable message providing more details about the error.
147
148 - `param: Optional[str]`
149
150 The name of the parameter that caused the error, if applicable.
151
152 - `object: Optional[str]`
153
154 The object type, which is always `list`.
155
156 - `expired_at: Optional[int]`
157
158 The Unix timestamp (in seconds) for when the batch expired.
159
160 - `expires_at: Optional[int]`
161
162 The Unix timestamp (in seconds) for when the batch will expire.
163
164 - `failed_at: Optional[int]`
165
166 The Unix timestamp (in seconds) for when the batch failed.
167
168 - `finalizing_at: Optional[int]`
169
170 The Unix timestamp (in seconds) for when the batch started finalizing.
171
172 - `in_progress_at: Optional[int]`
173
174 The Unix timestamp (in seconds) for when the batch started processing.
175
176 - `metadata: Optional[Metadata]`
177
178 Set of 16 key-value pairs that can be attached to an object. This can be
179 useful for storing additional information about the object in a structured
180 format, and querying for objects via API or the dashboard.
181
182 Keys are strings with a maximum length of 64 characters. Values are strings
183 with a maximum length of 512 characters.
184
185 - `model: Optional[str]`
186
187 Model ID used to process the batch, like `gpt-5-2025-08-07`. OpenAI
188 offers a wide range of models with different capabilities, performance
189 characteristics, and price points. Refer to the [model
190 guide](https://platform.openai.com/docs/models) to browse and compare available models.
191
192 - `output_file_id: Optional[str]`
193
194 The ID of the file containing the outputs of successfully executed requests.
195
196 - `request_counts: Optional[BatchRequestCounts]`
197
198 The request counts for different statuses within the batch.
199
200 - `completed: int`
201
202 Number of requests that have been completed successfully.
203
204 - `failed: int`
205
206 Number of requests that have failed.
207
208 - `total: int`
209
210 Total number of requests in the batch.
211
212 - `usage: Optional[BatchUsage]`
213
214 Represents token usage details including input tokens, output tokens, a
215 breakdown of output tokens, and the total tokens used. Only populated on
216 batches created after September 7, 2025.
217
218 - `input_tokens: int`
219
220 The number of input tokens.
221
222 - `input_tokens_details: InputTokensDetails`
223
224 A detailed breakdown of the input tokens.
225
226 - `cached_tokens: int`
227
228 The number of tokens that were retrieved from the cache. [More on
229 prompt caching](https://platform.openai.com/docs/guides/prompt-caching).
230
231 - `output_tokens: int`
232
233 The number of output tokens.
234
235 - `output_tokens_details: OutputTokensDetails`
236
237 A detailed breakdown of the output tokens.
238
239 - `reasoning_tokens: int`
240
241 The number of reasoning tokens.
242
243 - `total_tokens: int`
244
245 The total number of tokens used.
246
247### Example
248
249```python
250import os
251from openai import OpenAI
252
253client = OpenAI(
254 api_key=os.environ.get("OPENAI_API_KEY"), # This is the default and can be omitted
255)
256batch = client.batches.create(
257 completion_window="24h",
258 endpoint="/v1/responses",
259 input_file_id="input_file_id",
260)
261print(batch.id)
262```
263
264#### Response
265
266```json
267{
268 "id": "id",
269 "completion_window": "completion_window",
270 "created_at": 0,
271 "endpoint": "endpoint",
272 "input_file_id": "input_file_id",
273 "object": "batch",
274 "status": "validating",
275 "cancelled_at": 0,
276 "cancelling_at": 0,
277 "completed_at": 0,
278 "error_file_id": "error_file_id",
279 "errors": {
280 "data": [
281 {
282 "code": "code",
283 "line": 0,
284 "message": "message",
285 "param": "param"
286 }
287 ],
288 "object": "object"
289 },
290 "expired_at": 0,
291 "expires_at": 0,
292 "failed_at": 0,
293 "finalizing_at": 0,
294 "in_progress_at": 0,
295 "metadata": {
296 "foo": "string"
297 },
298 "model": "model",
299 "output_file_id": "output_file_id",
300 "request_counts": {
301 "completed": 0,
302 "failed": 0,
303 "total": 0
304 },
305 "usage": {
306 "input_tokens": 0,
307 "input_tokens_details": {
308 "cached_tokens": 0
309 },
310 "output_tokens": 0,
311 "output_tokens_details": {
312 "reasoning_tokens": 0
313 },
314 "total_tokens": 0
315 }
316}
317```
318
319### Example
320
321```python
322from openai import OpenAI
323client = OpenAI()
324
325client.batches.create(
326 input_file_id="file-abc123",
327 endpoint="/v1/chat/completions",
328 completion_window="24h"
329)
330```
331
332#### Response
333
334```json
335{
336 "id": "batch_abc123",
337 "object": "batch",
338 "endpoint": "/v1/chat/completions",
339 "errors": null,
340 "input_file_id": "file-abc123",
341 "completion_window": "24h",
342 "status": "validating",
343 "output_file_id": null,
344 "error_file_id": null,
345 "created_at": 1711471533,
346 "in_progress_at": null,
347 "expires_at": null,
348 "finalizing_at": null,
349 "completed_at": null,
350 "failed_at": null,
351 "expired_at": null,
352 "cancelling_at": null,
353 "cancelled_at": null,
354 "request_counts": {
355 "total": 0,
356 "completed": 0,
357 "failed": 0
358 },
359 "metadata": {
360 "customer_id": "user_123456789",
361 "batch_description": "Nightly eval job",
362 }
363}
364```