Batches

Create batch

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

post /batches

Create batch

Parameters

completion_window: Literal["24h"]

The time frame within which the batch should be processed. Currently only 24h is supported.
- "24h"
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.
- "/v1/responses"
- "/v1/chat/completions"
- "/v1/embeddings"
- "/v1/completions"
- "/v1/moderations"
- "/v1/images/generations"
- "/v1/images/edits"
- "/v1/videos"
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.
- anchor: Literal["created_at"]
  
  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.
  - "created_at"
- seconds: int
  
  The number of seconds after the anchor time that the file will expire. Must be between 3600 (1 hour) and 2592000 (30 days).

Returns

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.
- 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.
  - "batch"
- status: Literal["validating", "failed", "in_progress", 5 more]
  
  The current status of the batch.
  - "validating"
  - "failed"
  - "in_progress"
  - "finalizing"
  - "completed"
  - "expired"
  - "cancelling"
  - "cancelled"
- cancelled_at: Optional[int]
  
  The Unix timestamp (in seconds) for when the batch was cancelled.
- cancelling_at: Optional[int]
  
  The Unix timestamp (in seconds) for when the batch started cancelling.
- completed_at: Optional[int]
  
  The Unix timestamp (in seconds) for when the batch was completed.
- error_file_id: Optional[str]
  
  The ID of the file containing the outputs of requests with errors.
- errors: Optional[Errors]
  - data: Optional[List[object]]
  - object: Optional[str]
    
    The object type, which is always list.
- expired_at: Optional[int]
  
  The Unix timestamp (in seconds) for when the batch expired.
- expires_at: Optional[int]
  
  The Unix timestamp (in seconds) for when the batch will expire.
- failed_at: Optional[int]
  
  The Unix timestamp (in seconds) for when the batch failed.
- finalizing_at: Optional[int]
  
  The Unix timestamp (in seconds) for when the batch started finalizing.
- in_progress_at: Optional[int]
  
  The Unix timestamp (in seconds) for when the batch started processing.
- 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[object]
- 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.
  - input_tokens: int
    
    The number of input tokens.
  - input_tokens_details: InputTokensDetails
    
    A detailed breakdown of the input tokens.
    - cached_tokens: int
      
      The number of tokens that were retrieved from the cache. More on prompt caching.
  - output_tokens: int
    
    The number of output tokens.
  - output_tokens_details: OutputTokensDetails
    
    A detailed breakdown of the output tokens.
    - reasoning_tokens: int
      
      The number of reasoning tokens.
  - total_tokens: int
    
    The total number of tokens used.

Example

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ.get("OPENAI_API_KEY"),  # This is the default and can be omitted
)
batch = client.batches.create(
    completion_window="24h",
    endpoint="/v1/responses",
    input_file_id="input_file_id",
)
print(batch.id)

Response

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

Example

from openai import OpenAI
client = OpenAI()

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

Response

{
  "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",
  }
}

Retrieve batch

batches.retrieve(strbatch_id) -> Batch

get /batches/{batch_id}

Retrieve batch

Parameters

batch_id: str

Returns

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.
- 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.
  - "batch"
- status: Literal["validating", "failed", "in_progress", 5 more]
  
  The current status of the batch.
  - "validating"
  - "failed"
  - "in_progress"
  - "finalizing"
  - "completed"
  - "expired"
  - "cancelling"
  - "cancelled"
- cancelled_at: Optional[int]
  
  The Unix timestamp (in seconds) for when the batch was cancelled.
- cancelling_at: Optional[int]
  
  The Unix timestamp (in seconds) for when the batch started cancelling.
- completed_at: Optional[int]
  
  The Unix timestamp (in seconds) for when the batch was completed.
- error_file_id: Optional[str]
  
  The ID of the file containing the outputs of requests with errors.
- errors: Optional[Errors]
  - data: Optional[List[object]]
  - object: Optional[str]
    
    The object type, which is always list.
- expired_at: Optional[int]
  
  The Unix timestamp (in seconds) for when the batch expired.
- expires_at: Optional[int]
  
  The Unix timestamp (in seconds) for when the batch will expire.
- failed_at: Optional[int]
  
  The Unix timestamp (in seconds) for when the batch failed.
- finalizing_at: Optional[int]
  
  The Unix timestamp (in seconds) for when the batch started finalizing.
- in_progress_at: Optional[int]
  
  The Unix timestamp (in seconds) for when the batch started processing.
- 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[object]
- 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.
  - input_tokens: int
    
    The number of input tokens.
  - input_tokens_details: InputTokensDetails
    
    A detailed breakdown of the input tokens.
    - cached_tokens: int
      
      The number of tokens that were retrieved from the cache. More on prompt caching.
  - output_tokens: int
    
    The number of output tokens.
  - output_tokens_details: OutputTokensDetails
    
    A detailed breakdown of the output tokens.
    - reasoning_tokens: int
      
      The number of reasoning tokens.
  - total_tokens: int
    
    The total number of tokens used.

Example

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ.get("OPENAI_API_KEY"),  # This is the default and can be omitted
)
batch = client.batches.retrieve(
    "batch_id",
)
print(batch.id)

Response

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

Example

from openai import OpenAI
client = OpenAI()

client.batches.retrieve("batch_abc123")

Response

{
  "id": "batch_abc123",
  "object": "batch",
  "endpoint": "/v1/completions",
  "errors": null,
  "input_file_id": "file-abc123",
  "completion_window": "24h",
  "status": "completed",
  "output_file_id": "file-cvaTdG",
  "error_file_id": "file-HOWS94",
  "created_at": 1711471533,
  "in_progress_at": 1711471538,
  "expires_at": 1711557933,
  "finalizing_at": 1711493133,
  "completed_at": 1711493163,
  "failed_at": null,
  "expired_at": null,
  "cancelling_at": null,
  "cancelled_at": null,
  "request_counts": {
    "total": 100,
    "completed": 95,
    "failed": 5
  },
  "metadata": {
    "customer_id": "user_123456789",
    "batch_description": "Nightly eval job",
  }
}

Cancel batch

batches.cancel(strbatch_id) -> Batch

post /batches/{batch_id}/cancel

Cancel batch

Parameters

batch_id: str

Returns

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.
- 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.
  - "batch"
- status: Literal["validating", "failed", "in_progress", 5 more]
  
  The current status of the batch.
  - "validating"
  - "failed"
  - "in_progress"
  - "finalizing"
  - "completed"
  - "expired"
  - "cancelling"
  - "cancelled"
- cancelled_at: Optional[int]
  
  The Unix timestamp (in seconds) for when the batch was cancelled.
- cancelling_at: Optional[int]
  
  The Unix timestamp (in seconds) for when the batch started cancelling.
- completed_at: Optional[int]
  
  The Unix timestamp (in seconds) for when the batch was completed.
- error_file_id: Optional[str]
  
  The ID of the file containing the outputs of requests with errors.
- errors: Optional[Errors]
  - data: Optional[List[object]]
  - object: Optional[str]
    
    The object type, which is always list.
- expired_at: Optional[int]
  
  The Unix timestamp (in seconds) for when the batch expired.
- expires_at: Optional[int]
  
  The Unix timestamp (in seconds) for when the batch will expire.
- failed_at: Optional[int]
  
  The Unix timestamp (in seconds) for when the batch failed.
- finalizing_at: Optional[int]
  
  The Unix timestamp (in seconds) for when the batch started finalizing.
- in_progress_at: Optional[int]
  
  The Unix timestamp (in seconds) for when the batch started processing.
- 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[object]
- 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.
  - input_tokens: int
    
    The number of input tokens.
  - input_tokens_details: InputTokensDetails
    
    A detailed breakdown of the input tokens.
    - cached_tokens: int
      
      The number of tokens that were retrieved from the cache. More on prompt caching.
  - output_tokens: int
    
    The number of output tokens.
  - output_tokens_details: OutputTokensDetails
    
    A detailed breakdown of the output tokens.
    - reasoning_tokens: int
      
      The number of reasoning tokens.
  - total_tokens: int
    
    The total number of tokens used.

Example

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ.get("OPENAI_API_KEY"),  # This is the default and can be omitted
)
batch = client.batches.cancel(
    "batch_id",
)
print(batch.id)

Response

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

Example

from openai import OpenAI
client = OpenAI()

client.batches.cancel("batch_abc123")

Response

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

List batches

batches.list(BatchListParams**kwargs) -> SyncCursorPage[Batch]

get /batches

List batches

Parameters

after: Optional[str]

A cursor for use in pagination. after is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list.
limit: Optional[int]

A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20.

Returns

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.
- 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.
  - "batch"
- status: Literal["validating", "failed", "in_progress", 5 more]
  
  The current status of the batch.
  - "validating"
  - "failed"
  - "in_progress"
  - "finalizing"
  - "completed"
  - "expired"
  - "cancelling"
  - "cancelled"
- cancelled_at: Optional[int]
  
  The Unix timestamp (in seconds) for when the batch was cancelled.
- cancelling_at: Optional[int]
  
  The Unix timestamp (in seconds) for when the batch started cancelling.
- completed_at: Optional[int]
  
  The Unix timestamp (in seconds) for when the batch was completed.
- error_file_id: Optional[str]
  
  The ID of the file containing the outputs of requests with errors.
- errors: Optional[Errors]
  - data: Optional[List[object]]
  - object: Optional[str]
    
    The object type, which is always list.
- expired_at: Optional[int]
  
  The Unix timestamp (in seconds) for when the batch expired.
- expires_at: Optional[int]
  
  The Unix timestamp (in seconds) for when the batch will expire.
- failed_at: Optional[int]
  
  The Unix timestamp (in seconds) for when the batch failed.
- finalizing_at: Optional[int]
  
  The Unix timestamp (in seconds) for when the batch started finalizing.
- in_progress_at: Optional[int]
  
  The Unix timestamp (in seconds) for when the batch started processing.
- 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[object]
- 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.
  - input_tokens: int
    
    The number of input tokens.
  - input_tokens_details: InputTokensDetails
    
    A detailed breakdown of the input tokens.
    - cached_tokens: int
      
      The number of tokens that were retrieved from the cache. More on prompt caching.
  - output_tokens: int
    
    The number of output tokens.
  - output_tokens_details: OutputTokensDetails
    
    A detailed breakdown of the output tokens.
    - reasoning_tokens: int
      
      The number of reasoning tokens.
  - total_tokens: int
    
    The total number of tokens used.

Example

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ.get("OPENAI_API_KEY"),  # This is the default and can be omitted
)
page = client.batches.list()
page = page.data[0]
print(page.id)

Response

{
  "data": [
    {
      "id": "id",
      "completion_window": "completion_window",
      "created_at": 0,
      "endpoint": "endpoint",
      "input_file_id": "input_file_id",
      "object": "batch",
      "status": "validating",
      "cancelled_at": 0,
      "cancelling_at": 0,
      "completed_at": 0,
      "error_file_id": "error_file_id",
      "errors": {
        "data": [
          {}
        ],
        "object": "object"
      },
      "expired_at": 0,
      "expires_at": 0,
      "failed_at": 0,
      "finalizing_at": 0,
      "in_progress_at": 0,
      "metadata": {
        "foo": "string"
      },
      "model": "model",
      "output_file_id": "output_file_id",
      "request_counts": {},
      "usage": {
        "input_tokens": 0,
        "input_tokens_details": {
          "cached_tokens": 0
        },
        "output_tokens": 0,
        "output_tokens_details": {
          "reasoning_tokens": 0
        },
        "total_tokens": 0
      }
    }
  ],
  "has_more": true,
  "object": "list",
  "first_id": "batch_abc123",
  "last_id": "batch_abc456"
}

Example

from openai import OpenAI
client = OpenAI()

client.batches.list()

Response

{
  "object": "list",
  "data": [
    {
      "id": "batch_abc123",
      "object": "batch",
      "endpoint": "/v1/chat/completions",
      "errors": null,
      "input_file_id": "file-abc123",
      "completion_window": "24h",
      "status": "completed",
      "output_file_id": "file-cvaTdG",
      "error_file_id": "file-HOWS94",
      "created_at": 1711471533,
      "in_progress_at": 1711471538,
      "expires_at": 1711557933,
      "finalizing_at": 1711493133,
      "completed_at": 1711493163,
      "failed_at": null,
      "expired_at": null,
      "cancelling_at": null,
      "cancelled_at": null,
      "request_counts": {
        "total": 100,
        "completed": 95,
        "failed": 5
      },
      "metadata": {
        "customer_id": "user_123456789",
        "batch_description": "Nightly job",
      }
    },
    { ... },
  ],
  "first_id": "batch_abc123",
  "last_id": "batch_abc456",
  "has_more": true
}

Domain Types

Batch

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.
- 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.
  - "batch"
- status: Literal["validating", "failed", "in_progress", 5 more]
  
  The current status of the batch.
  - "validating"
  - "failed"
  - "in_progress"
  - "finalizing"
  - "completed"
  - "expired"
  - "cancelling"
  - "cancelled"
- cancelled_at: Optional[int]
  
  The Unix timestamp (in seconds) for when the batch was cancelled.
- cancelling_at: Optional[int]
  
  The Unix timestamp (in seconds) for when the batch started cancelling.
- completed_at: Optional[int]
  
  The Unix timestamp (in seconds) for when the batch was completed.
- error_file_id: Optional[str]
  
  The ID of the file containing the outputs of requests with errors.
- errors: Optional[Errors]
  - data: Optional[List[object]]
  - object: Optional[str]
    
    The object type, which is always list.
- expired_at: Optional[int]
  
  The Unix timestamp (in seconds) for when the batch expired.
- expires_at: Optional[int]
  
  The Unix timestamp (in seconds) for when the batch will expire.
- failed_at: Optional[int]
  
  The Unix timestamp (in seconds) for when the batch failed.
- finalizing_at: Optional[int]
  
  The Unix timestamp (in seconds) for when the batch started finalizing.
- in_progress_at: Optional[int]
  
  The Unix timestamp (in seconds) for when the batch started processing.
- 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[object]
- 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.
  - input_tokens: int
    
    The number of input tokens.
  - input_tokens_details: InputTokensDetails
    
    A detailed breakdown of the input tokens.
    - cached_tokens: int
      
      The number of tokens that were retrieved from the cache. More on prompt caching.
  - output_tokens: int
    
    The number of output tokens.
  - output_tokens_details: OutputTokensDetails
    
    A detailed breakdown of the output tokens.
    - reasoning_tokens: int
      
      The number of reasoning tokens.
  - total_tokens: int
    
    The total number of tokens used.

Batch Error

object

Batch Request Counts

object

Batch Usage

class 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.
- input_tokens: int
  
  The number of input tokens.
- input_tokens_details: InputTokensDetails
  
  A detailed breakdown of the input tokens.
  - cached_tokens: int
    
    The number of tokens that were retrieved from the cache. More on prompt caching.
- output_tokens: int
  
  The number of output tokens.
- output_tokens_details: OutputTokensDetails
  
  A detailed breakdown of the output tokens.
  - reasoning_tokens: int
    
    The number of reasoning tokens.
- total_tokens: int
  
  The total number of tokens used.

python/resources/batches/index.md +1340 −0 created

1# Batches

3## Create batch

5`batches.create(BatchCreateParams**kwargs) -> Batch`

7**post** `/batches`

9Create batch

11### Parameters

13- `completion_window: Literal["24h"]`

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

17 - `"24h"`

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

21 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.

23 - `"/v1/responses"`

25 - `"/v1/chat/completions"`

27 - `"/v1/embeddings"`

29 - `"/v1/completions"`

31 - `"/v1/moderations"`

33 - `"/v1/images/generations"`

35 - `"/v1/images/edits"`

37 - `"/v1/videos"`

39- `input_file_id: str`

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

43 See [upload file](https://platform.openai.com/docs/api-reference/files/create) for how to upload a file.

45 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.

47- `metadata: Optional[Metadata]`

49 Set of 16 key-value pairs that can be attached to an object. This can be

50 useful for storing additional information about the object in a structured

51 format, and querying for objects via API or the dashboard.

53 Keys are strings with a maximum length of 64 characters. Values are strings

54 with a maximum length of 512 characters.

56- `output_expires_after: Optional[OutputExpiresAfter]`

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

60 - `anchor: Literal["created_at"]`

62 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.

64 - `"created_at"`

66 - `seconds: int`

68 The number of seconds after the anchor time that the file will expire. Must be between 3600 (1 hour) and 2592000 (30 days).

70### Returns

72- `class Batch: …`

74 - `id: str`

76 - `completion_window: str`

78 The time frame within which the batch should be processed.

80 - `created_at: int`

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

84 - `endpoint: str`

86 The OpenAI API endpoint used by the batch.

88 - `input_file_id: str`

90 The ID of the input file for the batch.

92 - `object: Literal["batch"]`

94 The object type, which is always `batch`.

96 - `"batch"`

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

100 The current status of the batch.

101

102 - `"validating"`

103

104 - `"failed"`

105

106 - `"in_progress"`

107

108 - `"finalizing"`

109

110 - `"completed"`

111

112 - `"expired"`

113

114 - `"cancelling"`

115

116 - `"cancelled"`

117

118 - `cancelled_at: Optional[int]`

119

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

121

122 - `cancelling_at: Optional[int]`

123

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

125

126 - `completed_at: Optional[int]`

127

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

129

130 - `error_file_id: Optional[str]`

131

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

133

134 - `errors: Optional[Errors]`

135

136 - `data: Optional[List[object]]`

137

138 - `object: Optional[str]`

139

140 The object type, which is always `list`.

141

142 - `expired_at: Optional[int]`

143

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

145

146 - `expires_at: Optional[int]`

147

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

149

150 - `failed_at: Optional[int]`

151

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

153

154 - `finalizing_at: Optional[int]`

155

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

157

158 - `in_progress_at: Optional[int]`

159

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

161

162 - `metadata: Optional[Metadata]`

163

164 Set of 16 key-value pairs that can be attached to an object. This can be

165 useful for storing additional information about the object in a structured

166 format, and querying for objects via API or the dashboard.

167

168 Keys are strings with a maximum length of 64 characters. Values are strings

169 with a maximum length of 512 characters.

170

171 - `model: Optional[str]`

172

173 Model ID used to process the batch, like `gpt-5-2025-08-07`. OpenAI

174 offers a wide range of models with different capabilities, performance

175 characteristics, and price points. Refer to the [model

176 guide](https://platform.openai.com/docs/models) to browse and compare available models.

177

178 - `output_file_id: Optional[str]`

179

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

181

182 - `request_counts: Optional[object]`

183

184 - `usage: Optional[BatchUsage]`

185

186 Represents token usage details including input tokens, output tokens, a

187 breakdown of output tokens, and the total tokens used. Only populated on

188 batches created after September 7, 2025.

189

190 - `input_tokens: int`

191

192 The number of input tokens.

193

194 - `input_tokens_details: InputTokensDetails`

195

196 A detailed breakdown of the input tokens.

197

198 - `cached_tokens: int`

199

200 The number of tokens that were retrieved from the cache. [More on

201 prompt caching](https://platform.openai.com/docs/guides/prompt-caching).

202

203 - `output_tokens: int`

204

205 The number of output tokens.

206

207 - `output_tokens_details: OutputTokensDetails`

208

209 A detailed breakdown of the output tokens.

210

211 - `reasoning_tokens: int`

212

213 The number of reasoning tokens.

214

215 - `total_tokens: int`

216

217 The total number of tokens used.

218

219### Example

220

221```python

222import os

223from openai import OpenAI

224

225client = OpenAI(

226 api_key=os.environ.get("OPENAI_API_KEY"), # This is the default and can be omitted

227)

228batch = client.batches.create(

229 completion_window="24h",

230 endpoint="/v1/responses",

231 input_file_id="input_file_id",

232)

233print(batch.id)

234```

235

236#### Response

237

238```json

239{

240 "id": "id",

241 "completion_window": "completion_window",

242 "created_at": 0,

243 "endpoint": "endpoint",

244 "input_file_id": "input_file_id",

245 "object": "batch",

246 "status": "validating",

247 "cancelled_at": 0,

248 "cancelling_at": 0,

249 "completed_at": 0,

250 "error_file_id": "error_file_id",

251 "errors": {

252 "data": [

253 {}

254 ],

255 "object": "object"

256 },

257 "expired_at": 0,

258 "expires_at": 0,

259 "failed_at": 0,

260 "finalizing_at": 0,

261 "in_progress_at": 0,

262 "metadata": {

263 "foo": "string"

264 },

265 "model": "model",

266 "output_file_id": "output_file_id",

267 "request_counts": {},

268 "usage": {

269 "input_tokens": 0,

270 "input_tokens_details": {

271 "cached_tokens": 0

272 },

273 "output_tokens": 0,

274 "output_tokens_details": {

275 "reasoning_tokens": 0

276 },

277 "total_tokens": 0

278 }

279}

280```

281

282### Example

283

284```python

285from openai import OpenAI

286client = OpenAI()

287

288client.batches.create(

289 input_file_id="file-abc123",

290 endpoint="/v1/chat/completions",

291 completion_window="24h"

292)

293```

294

295#### Response

296

297```json

298{

299 "id": "batch_abc123",

300 "object": "batch",

301 "endpoint": "/v1/chat/completions",

302 "errors": null,

303 "input_file_id": "file-abc123",

304 "completion_window": "24h",

305 "status": "validating",

306 "output_file_id": null,

307 "error_file_id": null,

308 "created_at": 1711471533,

309 "in_progress_at": null,

310 "expires_at": null,

311 "finalizing_at": null,

312 "completed_at": null,

313 "failed_at": null,

314 "expired_at": null,

315 "cancelling_at": null,

316 "cancelled_at": null,

317 "request_counts": {

318 "total": 0,

319 "completed": 0,

320 "failed": 0

321 },

322 "metadata": {

323 "customer_id": "user_123456789",

324 "batch_description": "Nightly eval job",

325 }

326}

327```

328

329## Retrieve batch

330

331`batches.retrieve(strbatch_id) -> Batch`

332

333**get** `/batches/{batch_id}`

334

335Retrieve batch

336

337### Parameters

338

339- `batch_id: str`

340

341### Returns

342

343- `class Batch: …`

344

345 - `id: str`

346

347 - `completion_window: str`

348

349 The time frame within which the batch should be processed.

350

351 - `created_at: int`

352

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

354

355 - `endpoint: str`

356

357 The OpenAI API endpoint used by the batch.

358

359 - `input_file_id: str`

360

361 The ID of the input file for the batch.

362

363 - `object: Literal["batch"]`

364

365 The object type, which is always `batch`.

366

367 - `"batch"`

368

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

370

371 The current status of the batch.

372

373 - `"validating"`

374

375 - `"failed"`

376

377 - `"in_progress"`

378

379 - `"finalizing"`

380

381 - `"completed"`

382

383 - `"expired"`

384

385 - `"cancelling"`

386

387 - `"cancelled"`

388

389 - `cancelled_at: Optional[int]`

390

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

392

393 - `cancelling_at: Optional[int]`

394

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

396

397 - `completed_at: Optional[int]`

398

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

400

401 - `error_file_id: Optional[str]`

402

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

404

405 - `errors: Optional[Errors]`

406

407 - `data: Optional[List[object]]`

408

409 - `object: Optional[str]`

410

411 The object type, which is always `list`.

412

413 - `expired_at: Optional[int]`

414

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

416

417 - `expires_at: Optional[int]`

418

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

420

421 - `failed_at: Optional[int]`

422

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

424

425 - `finalizing_at: Optional[int]`

426

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

428

429 - `in_progress_at: Optional[int]`

430

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

432

433 - `metadata: Optional[Metadata]`

434

435 Set of 16 key-value pairs that can be attached to an object. This can be

436 useful for storing additional information about the object in a structured

437 format, and querying for objects via API or the dashboard.

438

439 Keys are strings with a maximum length of 64 characters. Values are strings

440 with a maximum length of 512 characters.

441

442 - `model: Optional[str]`

443

444 Model ID used to process the batch, like `gpt-5-2025-08-07`. OpenAI

445 offers a wide range of models with different capabilities, performance

446 characteristics, and price points. Refer to the [model

447 guide](https://platform.openai.com/docs/models) to browse and compare available models.

448

449 - `output_file_id: Optional[str]`

450

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

452

453 - `request_counts: Optional[object]`

454

455 - `usage: Optional[BatchUsage]`

456

457 Represents token usage details including input tokens, output tokens, a

458 breakdown of output tokens, and the total tokens used. Only populated on

459 batches created after September 7, 2025.

460

461 - `input_tokens: int`

462

463 The number of input tokens.

464

465 - `input_tokens_details: InputTokensDetails`

466

467 A detailed breakdown of the input tokens.

468

469 - `cached_tokens: int`

470

471 The number of tokens that were retrieved from the cache. [More on

472 prompt caching](https://platform.openai.com/docs/guides/prompt-caching).

473

474 - `output_tokens: int`

475

476 The number of output tokens.

477

478 - `output_tokens_details: OutputTokensDetails`

479

480 A detailed breakdown of the output tokens.

481

482 - `reasoning_tokens: int`

483

484 The number of reasoning tokens.

485

486 - `total_tokens: int`

487

488 The total number of tokens used.

489

490### Example

491

492```python

493import os

494from openai import OpenAI

495

496client = OpenAI(

497 api_key=os.environ.get("OPENAI_API_KEY"), # This is the default and can be omitted

498)

499batch = client.batches.retrieve(

500 "batch_id",

501)

502print(batch.id)

503```

504

505#### Response

506

507```json

508{

509 "id": "id",

510 "completion_window": "completion_window",

511 "created_at": 0,

512 "endpoint": "endpoint",

513 "input_file_id": "input_file_id",

514 "object": "batch",

515 "status": "validating",

516 "cancelled_at": 0,

517 "cancelling_at": 0,

518 "completed_at": 0,

519 "error_file_id": "error_file_id",

520 "errors": {

521 "data": [

522 {}

523 ],

524 "object": "object"

525 },

526 "expired_at": 0,

527 "expires_at": 0,

528 "failed_at": 0,

529 "finalizing_at": 0,

530 "in_progress_at": 0,

531 "metadata": {

532 "foo": "string"

533 },

534 "model": "model",

535 "output_file_id": "output_file_id",

536 "request_counts": {},

537 "usage": {

538 "input_tokens": 0,

539 "input_tokens_details": {

540 "cached_tokens": 0

541 },

542 "output_tokens": 0,

543 "output_tokens_details": {

544 "reasoning_tokens": 0

545 },

546 "total_tokens": 0

547 }

548}

549```

550

551### Example

552

553```python

554from openai import OpenAI

555client = OpenAI()

556

557client.batches.retrieve("batch_abc123")

558```

559

560#### Response

561

562```json

563{

564 "id": "batch_abc123",

565 "object": "batch",

566 "endpoint": "/v1/completions",

567 "errors": null,

568 "input_file_id": "file-abc123",

569 "completion_window": "24h",

570 "status": "completed",

571 "output_file_id": "file-cvaTdG",

572 "error_file_id": "file-HOWS94",

573 "created_at": 1711471533,

574 "in_progress_at": 1711471538,

575 "expires_at": 1711557933,

576 "finalizing_at": 1711493133,

577 "completed_at": 1711493163,

578 "failed_at": null,

579 "expired_at": null,

580 "cancelling_at": null,

581 "cancelled_at": null,

582 "request_counts": {

583 "total": 100,

584 "completed": 95,

585 "failed": 5

586 },

587 "metadata": {

588 "customer_id": "user_123456789",

589 "batch_description": "Nightly eval job",

590 }

591}

592```

593

594## Cancel batch

595

596`batches.cancel(strbatch_id) -> Batch`

597

598**post** `/batches/{batch_id}/cancel`

599

600Cancel batch

601

602### Parameters

603

604- `batch_id: str`

605

606### Returns

607

608- `class Batch: …`

609

610 - `id: str`

611

612 - `completion_window: str`

613

614 The time frame within which the batch should be processed.

615

616 - `created_at: int`

617

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

619

620 - `endpoint: str`

621

622 The OpenAI API endpoint used by the batch.

623

624 - `input_file_id: str`

625

626 The ID of the input file for the batch.

627

628 - `object: Literal["batch"]`

629

630 The object type, which is always `batch`.

631

632 - `"batch"`

633

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

635

636 The current status of the batch.

637

638 - `"validating"`

639

640 - `"failed"`

641

642 - `"in_progress"`

643

644 - `"finalizing"`

645

646 - `"completed"`

647

648 - `"expired"`

649

650 - `"cancelling"`

651

652 - `"cancelled"`

653

654 - `cancelled_at: Optional[int]`

655

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

657

658 - `cancelling_at: Optional[int]`

659

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

661

662 - `completed_at: Optional[int]`

663

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

665

666 - `error_file_id: Optional[str]`

667

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

669

670 - `errors: Optional[Errors]`

671

672 - `data: Optional[List[object]]`

673

674 - `object: Optional[str]`

675

676 The object type, which is always `list`.

677

678 - `expired_at: Optional[int]`

679

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

681

682 - `expires_at: Optional[int]`

683

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

685

686 - `failed_at: Optional[int]`

687

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

689

690 - `finalizing_at: Optional[int]`

691

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

693

694 - `in_progress_at: Optional[int]`

695

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

697

698 - `metadata: Optional[Metadata]`

699

700 Set of 16 key-value pairs that can be attached to an object. This can be

701 useful for storing additional information about the object in a structured

702 format, and querying for objects via API or the dashboard.

703

704 Keys are strings with a maximum length of 64 characters. Values are strings

705 with a maximum length of 512 characters.

706

707 - `model: Optional[str]`

708

709 Model ID used to process the batch, like `gpt-5-2025-08-07`. OpenAI

710 offers a wide range of models with different capabilities, performance

711 characteristics, and price points. Refer to the [model

712 guide](https://platform.openai.com/docs/models) to browse and compare available models.

713

714 - `output_file_id: Optional[str]`

715

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

717

718 - `request_counts: Optional[object]`

719

720 - `usage: Optional[BatchUsage]`

721

722 Represents token usage details including input tokens, output tokens, a

723 breakdown of output tokens, and the total tokens used. Only populated on

724 batches created after September 7, 2025.

725

726 - `input_tokens: int`

727

728 The number of input tokens.

729

730 - `input_tokens_details: InputTokensDetails`

731

732 A detailed breakdown of the input tokens.

733

734 - `cached_tokens: int`

735

736 The number of tokens that were retrieved from the cache. [More on

737 prompt caching](https://platform.openai.com/docs/guides/prompt-caching).

738

739 - `output_tokens: int`

740

741 The number of output tokens.

742

743 - `output_tokens_details: OutputTokensDetails`

744

745 A detailed breakdown of the output tokens.

746

747 - `reasoning_tokens: int`

748

749 The number of reasoning tokens.

750

751 - `total_tokens: int`

752

753 The total number of tokens used.

754

755### Example

756

757```python

758import os

759from openai import OpenAI

760

761client = OpenAI(

762 api_key=os.environ.get("OPENAI_API_KEY"), # This is the default and can be omitted

763)

764batch = client.batches.cancel(

765 "batch_id",

766)

767print(batch.id)

768```

769

770#### Response

771

772```json

773{

774 "id": "id",

775 "completion_window": "completion_window",

776 "created_at": 0,

777 "endpoint": "endpoint",

778 "input_file_id": "input_file_id",

779 "object": "batch",

780 "status": "validating",

781 "cancelled_at": 0,

782 "cancelling_at": 0,

783 "completed_at": 0,

784 "error_file_id": "error_file_id",

785 "errors": {

786 "data": [

787 {}

788 ],

789 "object": "object"

790 },

791 "expired_at": 0,

792 "expires_at": 0,

793 "failed_at": 0,

794 "finalizing_at": 0,

795 "in_progress_at": 0,

796 "metadata": {

797 "foo": "string"

798 },

799 "model": "model",

800 "output_file_id": "output_file_id",

801 "request_counts": {},

802 "usage": {

803 "input_tokens": 0,

804 "input_tokens_details": {

805 "cached_tokens": 0

806 },

807 "output_tokens": 0,

808 "output_tokens_details": {

809 "reasoning_tokens": 0

810 },

811 "total_tokens": 0

812 }

813}

814```

815

816### Example

817

818```python

819from openai import OpenAI

820client = OpenAI()

821

822client.batches.cancel("batch_abc123")

823```

824

825#### Response

826

827```json

828{

829 "id": "batch_abc123",

830 "object": "batch",

831 "endpoint": "/v1/chat/completions",

832 "errors": null,

833 "input_file_id": "file-abc123",

834 "completion_window": "24h",

835 "status": "cancelling",

836 "output_file_id": null,

837 "error_file_id": null,

838 "created_at": 1711471533,

839 "in_progress_at": 1711471538,

840 "expires_at": 1711557933,

841 "finalizing_at": null,

842 "completed_at": null,

843 "failed_at": null,

844 "expired_at": null,

845 "cancelling_at": 1711475133,

846 "cancelled_at": null,

847 "request_counts": {

848 "total": 100,

849 "completed": 23,

850 "failed": 1

851 },

852 "metadata": {

853 "customer_id": "user_123456789",

854 "batch_description": "Nightly eval job",

855 }

856}

857```

858

859## List batches

860

861`batches.list(BatchListParams**kwargs) -> SyncCursorPage[Batch]`

862

863**get** `/batches`

864

865List batches

866

867### Parameters

868

869- `after: Optional[str]`

870

871 A cursor for use in pagination. `after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list.

872

873- `limit: Optional[int]`

874

875 A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20.

876

877### Returns

878

879- `class Batch: …`

880

881 - `id: str`

882

883 - `completion_window: str`

884

885 The time frame within which the batch should be processed.

886

887 - `created_at: int`

888

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

890

891 - `endpoint: str`

892

893 The OpenAI API endpoint used by the batch.

894

895 - `input_file_id: str`

896

897 The ID of the input file for the batch.

898

899 - `object: Literal["batch"]`

900

901 The object type, which is always `batch`.

902

903 - `"batch"`

904

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

906

907 The current status of the batch.

908

909 - `"validating"`

910

911 - `"failed"`

912

913 - `"in_progress"`

914

915 - `"finalizing"`

916

917 - `"completed"`

918

919 - `"expired"`

920

921 - `"cancelling"`

922

923 - `"cancelled"`

924

925 - `cancelled_at: Optional[int]`

926

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

928

929 - `cancelling_at: Optional[int]`

930

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

932

933 - `completed_at: Optional[int]`

934

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

936

937 - `error_file_id: Optional[str]`

938

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

940

941 - `errors: Optional[Errors]`

942

943 - `data: Optional[List[object]]`

944

945 - `object: Optional[str]`

946

947 The object type, which is always `list`.

948

949 - `expired_at: Optional[int]`

950

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

952

953 - `expires_at: Optional[int]`

954

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

956

957 - `failed_at: Optional[int]`

958

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

960

961 - `finalizing_at: Optional[int]`

962

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

964

965 - `in_progress_at: Optional[int]`

966

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

968

969 - `metadata: Optional[Metadata]`

970

971 Set of 16 key-value pairs that can be attached to an object. This can be

972 useful for storing additional information about the object in a structured

973 format, and querying for objects via API or the dashboard.

974

975 Keys are strings with a maximum length of 64 characters. Values are strings

976 with a maximum length of 512 characters.

977

978 - `model: Optional[str]`

979

980 Model ID used to process the batch, like `gpt-5-2025-08-07`. OpenAI

981 offers a wide range of models with different capabilities, performance

982 characteristics, and price points. Refer to the [model

983 guide](https://platform.openai.com/docs/models) to browse and compare available models.

984

985 - `output_file_id: Optional[str]`

986

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

988

989 - `request_counts: Optional[object]`

990

991 - `usage: Optional[BatchUsage]`

992

993 Represents token usage details including input tokens, output tokens, a

994 breakdown of output tokens, and the total tokens used. Only populated on

995 batches created after September 7, 2025.

996

997 - `input_tokens: int`

998

999 The number of input tokens.

1000

1001 - `input_tokens_details: InputTokensDetails`

1002

1003 A detailed breakdown of the input tokens.

1004

1005 - `cached_tokens: int`

1006

1007 The number of tokens that were retrieved from the cache. [More on

1008 prompt caching](https://platform.openai.com/docs/guides/prompt-caching).

1009

1010 - `output_tokens: int`

1011

1012 The number of output tokens.

1013

1014 - `output_tokens_details: OutputTokensDetails`

1015

1016 A detailed breakdown of the output tokens.

1017

1018 - `reasoning_tokens: int`

1019

1020 The number of reasoning tokens.

1021

1022 - `total_tokens: int`

1023

1024 The total number of tokens used.

1025

1026### Example

1027

1028```python

1029import os

1030from openai import OpenAI

1031

1032client = OpenAI(

1033 api_key=os.environ.get("OPENAI_API_KEY"), # This is the default and can be omitted

1034)

1035page = client.batches.list()

1036page = page.data[0]

1037print(page.id)

1038```

1039

1040#### Response

1041

1042```json

1043{

1044 "data": [

1045 {

1046 "id": "id",

1047 "completion_window": "completion_window",

1048 "created_at": 0,

1049 "endpoint": "endpoint",

1050 "input_file_id": "input_file_id",

1051 "object": "batch",

1052 "status": "validating",

1053 "cancelled_at": 0,

1054 "cancelling_at": 0,

1055 "completed_at": 0,

1056 "error_file_id": "error_file_id",

1057 "errors": {

1058 "data": [

1059 {}

1060 ],

1061 "object": "object"

1062 },

1063 "expired_at": 0,

1064 "expires_at": 0,

1065 "failed_at": 0,

1066 "finalizing_at": 0,

1067 "in_progress_at": 0,

1068 "metadata": {

1069 "foo": "string"

1070 },

1071 "model": "model",

1072 "output_file_id": "output_file_id",

1073 "request_counts": {},

1074 "usage": {

1075 "input_tokens": 0,

1076 "input_tokens_details": {

1077 "cached_tokens": 0

1078 },

1079 "output_tokens": 0,

1080 "output_tokens_details": {

1081 "reasoning_tokens": 0

1082 },

1083 "total_tokens": 0

1084 }

1085 }

1086 ],

1087 "has_more": true,

1088 "object": "list",

1089 "first_id": "batch_abc123",

1090 "last_id": "batch_abc456"

1091}

1092```

1093

1094### Example

1095

1096```python

1097from openai import OpenAI

1098client = OpenAI()

1099

1100client.batches.list()

1101```

1102

1103#### Response

1104

1105```json

1106{

1107 "object": "list",

1108 "data": [

1109 {

1110 "id": "batch_abc123",

1111 "object": "batch",

1112 "endpoint": "/v1/chat/completions",

1113 "errors": null,

1114 "input_file_id": "file-abc123",

1115 "completion_window": "24h",

1116 "status": "completed",

1117 "output_file_id": "file-cvaTdG",

1118 "error_file_id": "file-HOWS94",

1119 "created_at": 1711471533,

1120 "in_progress_at": 1711471538,

1121 "expires_at": 1711557933,

1122 "finalizing_at": 1711493133,

1123 "completed_at": 1711493163,

1124 "failed_at": null,

1125 "expired_at": null,

1126 "cancelling_at": null,

1127 "cancelled_at": null,

1128 "request_counts": {

1129 "total": 100,

1130 "completed": 95,

1131 "failed": 5

1132 },

1133 "metadata": {

1134 "customer_id": "user_123456789",

1135 "batch_description": "Nightly job",

1136 }

1137 },

1138 { ... },

1139 ],

1140 "first_id": "batch_abc123",

1141 "last_id": "batch_abc456",

1142 "has_more": true

1143}

1144```

1145

1146## Domain Types

1147

1148### Batch

1149

1150- `class Batch: …`

1151

1152 - `id: str`

1153

1154 - `completion_window: str`

1155

1156 The time frame within which the batch should be processed.

1157

1158 - `created_at: int`

1159

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

1161

1162 - `endpoint: str`

1163

1164 The OpenAI API endpoint used by the batch.

1165

1166 - `input_file_id: str`

1167

1168 The ID of the input file for the batch.

1169

1170 - `object: Literal["batch"]`

1171

1172 The object type, which is always `batch`.

1173

1174 - `"batch"`

1175

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

1177

1178 The current status of the batch.

1179

1180 - `"validating"`

1181

1182 - `"failed"`

1183

1184 - `"in_progress"`

1185

1186 - `"finalizing"`

1187

1188 - `"completed"`

1189

1190 - `"expired"`

1191

1192 - `"cancelling"`

1193

1194 - `"cancelled"`

1195

1196 - `cancelled_at: Optional[int]`

1197

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

1199

1200 - `cancelling_at: Optional[int]`

1201

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

1203

1204 - `completed_at: Optional[int]`

1205

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

1207

1208 - `error_file_id: Optional[str]`

1209

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

1211

1212 - `errors: Optional[Errors]`

1213

1214 - `data: Optional[List[object]]`

1215

1216 - `object: Optional[str]`

1217

1218 The object type, which is always `list`.

1219

1220 - `expired_at: Optional[int]`

1221

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

1223

1224 - `expires_at: Optional[int]`

1225

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

1227

1228 - `failed_at: Optional[int]`

1229

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

1231

1232 - `finalizing_at: Optional[int]`

1233

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

1235

1236 - `in_progress_at: Optional[int]`

1237

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

1239

1240 - `metadata: Optional[Metadata]`

1241

1242 Set of 16 key-value pairs that can be attached to an object. This can be

1243 useful for storing additional information about the object in a structured

1244 format, and querying for objects via API or the dashboard.

1245

1246 Keys are strings with a maximum length of 64 characters. Values are strings

1247 with a maximum length of 512 characters.

1248

1249 - `model: Optional[str]`

1250

1251 Model ID used to process the batch, like `gpt-5-2025-08-07`. OpenAI

1252 offers a wide range of models with different capabilities, performance

1253 characteristics, and price points. Refer to the [model

1254 guide](https://platform.openai.com/docs/models) to browse and compare available models.

1255

1256 - `output_file_id: Optional[str]`

1257

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

1259

1260 - `request_counts: Optional[object]`

1261

1262 - `usage: Optional[BatchUsage]`

1263

1264 Represents token usage details including input tokens, output tokens, a

1265 breakdown of output tokens, and the total tokens used. Only populated on

1266 batches created after September 7, 2025.

1267

1268 - `input_tokens: int`

1269

1270 The number of input tokens.

1271

1272 - `input_tokens_details: InputTokensDetails`

1273

1274 A detailed breakdown of the input tokens.

1275

1276 - `cached_tokens: int`

1277

1278 The number of tokens that were retrieved from the cache. [More on

1279 prompt caching](https://platform.openai.com/docs/guides/prompt-caching).

1280

1281 - `output_tokens: int`

1282

1283 The number of output tokens.

1284

1285 - `output_tokens_details: OutputTokensDetails`

1286

1287 A detailed breakdown of the output tokens.

1288

1289 - `reasoning_tokens: int`

1290

1291 The number of reasoning tokens.

1292

1293 - `total_tokens: int`

1294

1295 The total number of tokens used.

1296

1297### Batch Error

1298

1299- `object`

1300

1301### Batch Request Counts

1302

1303- `object`

1304

1305### Batch Usage

1306

1307- `class BatchUsage: …`

1308

1309 Represents token usage details including input tokens, output tokens, a

1310 breakdown of output tokens, and the total tokens used. Only populated on

1311 batches created after September 7, 2025.

1312

1313 - `input_tokens: int`

1314

1315 The number of input tokens.

1316

1317 - `input_tokens_details: InputTokensDetails`

1318

1319 A detailed breakdown of the input tokens.

1320

1321 - `cached_tokens: int`

1322

1323 The number of tokens that were retrieved from the cache. [More on

1324 prompt caching](https://platform.openai.com/docs/guides/prompt-caching).

1325

1326 - `output_tokens: int`

1327

1328 The number of output tokens.

1329

1330 - `output_tokens_details: OutputTokensDetails`

1331

1332 A detailed breakdown of the output tokens.

1333

1334 - `reasoning_tokens: int`

1335

1336 The number of reasoning tokens.

1337

1338 - `total_tokens: int`

1339

1340 The total number of tokens used.

python/resources/batches/index.md 2026-07-07 08:02 UTC to 2026-07-09 20:58 UTC

Batches

Create batch

Parameters

Returns

Example

Response

Example

Response

Retrieve batch

Parameters

Returns

Example

Response

Example

Response

Cancel batch

Parameters

Returns

Example

Response

Example

Response

List batches

Parameters

Returns

Example

Response

Example

Response

Domain Types

Batch

Batch Error

Batch Request Counts

Batch Usage