curl -X POST 'https://api.openai.com/v1/batches' \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "input_file_id": "input-file-id",
  "endpoint": "/v1/responses",
  "completion_window": "24h"
}'

# POST /batches (OpenAI API)
Base URL: https://api.openai.com/v1
Auth: Authorization; OpenAI API key; required.
Request formats: application/json.
Last verified: 2026-10-20

> Create batch

## Critical Gotchas
* The Responses API is the primary interface for new text and tool workflows; Chat Completions remains a separate compatibility API.
* Audio transcription uploads use multipart form data rather than a JSON request body.

## cURL
curl -X POST 'https://api.openai.com/v1/batches' \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "input_file_id": "input-file-id",
  "endpoint": "/v1/responses",
  "completion_window": "24h"
}'

## Parameters
| Name | In | Type | Required | Description |
| :--- | :--- | :--- | :--- | :--- |
| input_file_id | body | string | Yes | The ID of an uploaded file that contains requests for the new batch.  See [up... |
| endpoint | body | string | Yes | The endpoint to be used for all requests in the batch. Currently `/v1/respons... |
| completion_window | body | string | Yes | The time frame within which the batch should be processed. Currently only `24... |
| metadata | body | object | No | Set of 16 key-value pairs that can be attached to an object. This can be usef... |
| output_expires_after | body | object | No | The expiration policy for the output and/or error file that are generated for... |

## Response example
{"id":"string","object":"batch"}

---
Need an API key? Get one at https://platform.openai.com/api-keys

POST

POST /batches — OpenAI API

OpenAI API key (required); https://api.openai.com/v1

OpenAI API

Create batch

Base URL: https://api.openai.com/v1
Auth: Authorization: Bearer <OPENAI_API_KEY>
Last verified: 2026-10-20 · upstream hash matched

Actions Try in browser→

Agents: curl -H "Accept: text/markdown" this URL
→ 316 tokens · Vary: Accept

Critical gotchas

The Responses API is the primary interface for new text and tool workflows; Chat Completions remains a separate compatibility API.

Audio transcription uploads use multipart form data rather than a JSON request body.

cURL

curl -X POST 'https://api.openai.com/v1/batches' \  -H "Authorization: Bearer $OPENAI_API_KEY" \  -H 'Content-Type: application/json' \  -d '{  "input_file_id": "input-file-id",  "endpoint": "/v1/responses",  "completion_window": "24h"}'

Parameters

Name	In	Type	Required	Description
input_file_id	body	string	Yes	The ID of an uploaded file that contains requests for the new batch. See [upload file](https://developers.openai.com/api/reference/resources/files/methods/create) for how to upload a file. Your input file must be formatted as a [JSONL file](https://developers.openai.com/api/docs/guides/batch#1-prepare-your-batch-file), 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.
endpoint	body	string	Yes	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.
completion_window	body	string	Yes	The time frame within which the batch should be processed. Currently only `24h` is supported.
metadata	body	object	No	Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format, and querying for objects via API or the dashboard. Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters.
output_expires_after	body	object	No	The expiration policy for the output and/or error file that are generated for a batch.

Response 200 OK

{
  "id": "string",
  "object": "batch",
  "endpoint": "string",
  "model": "string",
  "errors": {
    "object": "string",
    "data": [
      {
        "code": "string",
        "message": "string",
        "param": "string",
        "line": 0
      }
    ]
  },
  "input_file_id": "string",
  "completion_window": "string",
  "status": "validating",
  "output_file_id": "string",
  "error_file_id": "string",
  "created_at": 0,
  "in_progress_at": 0,
  "expires_at": 0,
  "finalizing_at": 0,
  "completed_at": 0,
  "failed_at": 0,
  "expired_at": 0,
  "cancelling_at": 0,
  "cancelled_at": 0,
  "request_counts": {
    "total": 0,
    "completed": 0,
    "failed": 0
  },
  "usage": {
    "input_tokens": 0,
    "input_tokens_details": {
      "cached_tokens": 0
    },
    "output_tokens": 0,
    "output_tokens_details": {
      "reasoning_tokens": 0
    },
    "total_tokens": 0
  },
  "metadata": {}
}

Get a free OpenAI API key → sponsored

Affiliate link - we may earn a commission, at no extra cost to you.