Skip to content
For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.
Primary navigation

Suggested
Overview Models Agents Tools Voice & Audio Production API reference
API Dashboard
Try ChatGPT
API Reference
Batches

Create batch

batches.create(BatchCreateParams**kwargs) -> Batch
POST/batches

Creates and executes a batch from an uploaded file of requests

ParametersExpand Collapse
completion_window: Literal["24h"]

The time frame within which the batch should be processed. Currently only 24h is supported.

endpoint: Literal["/v1/responses", "/v1/chat/completions", "/v1/embeddings", 5 more]

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.

input_file_id: str

The ID of an uploaded file that contains requests for the new batch.

See upload file for how to upload a file.

Your input file must be formatted as a JSONL 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.

metadata: Optional[Metadata]

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: Optional[OutputExpiresAfter]

The expiration policy for the output and/or error file that are generated for a batch.

ReturnsExpand Collapse
class Batch: …
id: str
completion_window: str

The time frame within which the batch should be processed.

created_at: int

The Unix timestamp (in seconds) for when the batch was created.

formatunixtime
endpoint: str

The OpenAI API endpoint used by the batch.

input_file_id: str

The ID of the input file for the batch.

object: Literal["batch"]

The object type, which is always batch.

status: Literal["validating", "failed", "in_progress", 5 more]

The current status of the batch.

cancelled_at: Optional[int]

The Unix timestamp (in seconds) for when the batch was cancelled.

formatunixtime
cancelling_at: Optional[int]

The Unix timestamp (in seconds) for when the batch started cancelling.

formatunixtime
completed_at: Optional[int]

The Unix timestamp (in seconds) for when the batch was completed.

formatunixtime
error_file_id: Optional[str]

The ID of the file containing the outputs of requests with errors.

errors: Optional[Errors]
expired_at: Optional[int]

The Unix timestamp (in seconds) for when the batch expired.

formatunixtime
expires_at: Optional[int]

The Unix timestamp (in seconds) for when the batch will expire.

formatunixtime
failed_at: Optional[int]

The Unix timestamp (in seconds) for when the batch failed.

formatunixtime
finalizing_at: Optional[int]

The Unix timestamp (in seconds) for when the batch started finalizing.

formatunixtime
in_progress_at: Optional[int]

The Unix timestamp (in seconds) for when the batch started processing.

formatunixtime
metadata: Optional[Metadata]

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.

model: Optional[str]

Model ID used to process the batch, like gpt-5-2025-08-07. OpenAI offers a wide range of models with different capabilities, performance characteristics, and price points. Refer to the model guide to browse and compare available models.

output_file_id: Optional[str]

The ID of the file containing the outputs of successfully executed requests.

request_counts: Optional[BatchRequestCounts]

The request counts for different statuses within the batch.

usage: Optional[BatchUsage]

Represents token usage details including input tokens, output tokens, a breakdown of output tokens, and the total tokens used. Only populated on batches created after September 7, 2025.

Create batch

from openai import OpenAI
client = OpenAI()

client.batches.create(
  input_file_id="file-abc123",
  endpoint="/v1/chat/completions",
  completion_window="24h"
)

{
  "id": "batch_abc123",
  "object": "batch",
  "endpoint": "/v1/chat/completions",
  "errors": null,
  "input_file_id": "file-abc123",
  "completion_window": "24h",
  "status": "validating",
  "output_file_id": null,
  "error_file_id": null,
  "created_at": 1711471533,
  "in_progress_at": null,
  "expires_at": null,
  "finalizing_at": null,
  "completed_at": null,
  "failed_at": null,
  "expired_at": null,
  "cancelling_at": null,
  "cancelled_at": null,
  "request_counts": {
    "total": 0,
    "completed": 0,
    "failed": 0
  },
  "metadata": {
    "customer_id": "user_123456789",
    "batch_description": "Nightly eval job",
  }
}
Returns Examples
{
  "id": "batch_abc123",
  "object": "batch",
  "endpoint": "/v1/chat/completions",
  "errors": null,
  "input_file_id": "file-abc123",
  "completion_window": "24h",
  "status": "validating",
  "output_file_id": null,
  "error_file_id": null,
  "created_at": 1711471533,
  "in_progress_at": null,
  "expires_at": null,
  "finalizing_at": null,
  "completed_at": null,
  "failed_at": null,
  "expired_at": null,
  "cancelling_at": null,
  "cancelled_at": null,
  "request_counts": {
    "total": 0,
    "completed": 0,
    "failed": 0
  },
  "metadata": {
    "customer_id": "user_123456789",
    "batch_description": "Nightly eval job",
  }
}