Batch API: run large jobs asynchronously, processed in the EU

POST /v1/batches creates a job from a file you have already uploaded with purpose batch. Pass its input_file_id, the endpoint that every line targets, such as /v1/chat/completions, /v1/responses or /v1/embeddings, and completion_window, which is 24h. Optional metadata lets you tag the job with your own labels.

The response is a batch object with an id and a status. The job runs in the background, separate from your interactive traffic, so a large backlog does not compete with requests your users are waiting for. The requests and results never leave European data centres.

Poll GET /v1/batches/{batch_id} to follow progress. status moves from validating to in_progress and finalizing, then ends as completed, failed, expired or cancelled. request_counts shows total, completed and failed so you can display progress.

When the batch is completed, output_file_id points to a JSONL file. Each line has the custom_id from your input and a response with the status_code and the normal response body. Lines are not in input order, so match on custom_id. Failed requests go to a separate file referenced by error_file_id. POST /v1/batches/{batch_id}/cancel stops a job, and GET /v1/batches lists your jobs.

Generate the input file from your database, with a custom_id that is the record's primary key. Validate every line locally, upload the file, create the batch, and store the batch id against the job in your own system. A scheduled task checks the status every few minutes rather than holding a connection open.

When the batch completes, download the output, write the results back by custom_id, and collect any errors into a new, smaller input file to retry. Then delete the input and output files. Running a test batch of fifty lines first catches prompt or schema problems before you spend a large job on them.

A batch that fails validation, because of malformed JSON, a missing custom_id, duplicate ids or lines that target a different endpoint, ends with status failed and an errors list naming the problem and line. Fix the file and submit a new batch.

Individual requests can fail inside an otherwise successful batch, for example when one prompt exceeds the context window; those appear in the error file and do not stop the rest. If a batch is not finished within the window it becomes expired, and results for completed requests are still available. Batch size limits and throughput depend on your plan, and we confirm them with you.