OpenAI Batch API JSONL format
Updated November 4, 2026
An OpenAI Batch API input file is a .jsonl file with one request per line. Each line needs a unique custom_id, a method of POST, a url, and a body holding the usual endpoint parameters. A file can hold up to 50,000 requests and 200 MB, and can use only one model.
This page summarizes OpenAI’s Batch API guide, checked on November 4, 2026.
Input line
{"custom_id": "request-1", "method": "POST", "url": "/v1/responses", "body": {"model": "MODEL_NAME", "input": "Reply with the word blue.", "max_output_tokens": 64}}
| Field | Rule |
|---|---|
custom_id |
Required string, unique within the file |
method |
POST |
url |
One of the supported endpoints listed below |
body |
Object with the same parameters as the endpoint |
Supported url values: /v1/responses, /v1/chat/completions, /v1/embeddings, /v1/completions, /v1/moderations, /v1/images/generations and /v1/images/edits.
Output line
The output file has one line for each successful request:
{"id": "batch_req_1", "custom_id": "request-1", "response": {"status_code": 200, "request_id": "req_1", "body": {"id": "resp_1", "object": "response", "status": "completed"}}, "error": null}
Output order may not match input order, so always map results by custom_id.
Error line
Failed requests go to a separate file, found through the batch’s error_file_id:
{"id": "batch_req_123", "custom_id": "request-3", "response": null, "error": {"code": "batch_expired", "message": "This request could not be executed before the completion window expired."}}
Limits
| Limit | Value |
|---|---|
| Requests per batch | 50,000 |
| Input file size | 200 MB |
| Models per file | 1 |
| Embedding inputs per batch | 50,000 across all requests |
| Completion window | 24 hours |
| Batches created per hour | 2,000 |
| Output file retention | Deleted 30 days after the batch completes |
There is also a per-model limit on queued prompt tokens, shown in your platform settings.
Workflow
- Check your file with the JSONL validator, using the OpenAI Batch API profile.
- If it is over the limits, use the JSONL splitter.
- Upload and create the batch.
- Download the output file and any error file.
- Add all of them to the batch results analyzer to see what failed and to build a retry file.