Batches

Create batch

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

post /batches

Creates and executes a batch from an uploaded file of requests

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[BatchError]]
    - code: Optional[str]
      
      An error code identifying the error type.
    - line: Optional[int]
      
      The line number of the input file where the error occurred, if applicable.
    - message: Optional[str]
      
      A human-readable message providing more details about the error.
    - param: Optional[str]
      
      The name of the parameter that caused the error, if applicable.
  - 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[BatchRequestCounts]
  
  The request counts for different statuses within the batch.
  - completed: int
    
    Number of requests that have been completed successfully.
  - failed: int
    
    Number of requests that have failed.
  - total: int
    
    Total number of requests in 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.
  - 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": [
      {
        "code": "code",
        "line": 0,
        "message": "message",
        "param": "param"
      }
    ],
    "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": {
    "completed": 0,
    "failed": 0,
    "total": 0
  },
  "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}

Retrieves a 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[BatchError]]
    - code: Optional[str]
      
      An error code identifying the error type.
    - line: Optional[int]
      
      The line number of the input file where the error occurred, if applicable.
    - message: Optional[str]
      
      A human-readable message providing more details about the error.
    - param: Optional[str]
      
      The name of the parameter that caused the error, if applicable.
  - 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[BatchRequestCounts]
  
  The request counts for different statuses within the batch.
  - completed: int
    
    Number of requests that have been completed successfully.
  - failed: int
    
    Number of requests that have failed.
  - total: int
    
    Total number of requests in 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.
  - 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": [
      {
        "code": "code",
        "line": 0,
        "message": "message",
        "param": "param"
      }
    ],
    "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": {
    "completed": 0,
    "failed": 0,
    "total": 0
  },
  "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

Cancels an in-progress batch. The batch will be in status cancelling for up to 10 minutes, before changing to cancelled, where it will have partial results (if any) available in the output file.

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[BatchError]]
    - code: Optional[str]
      
      An error code identifying the error type.
    - line: Optional[int]
      
      The line number of the input file where the error occurred, if applicable.
    - message: Optional[str]
      
      A human-readable message providing more details about the error.
    - param: Optional[str]
      
      The name of the parameter that caused the error, if applicable.
  - 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[BatchRequestCounts]
  
  The request counts for different statuses within the batch.
  - completed: int
    
    Number of requests that have been completed successfully.
  - failed: int
    
    Number of requests that have failed.
  - total: int
    
    Total number of requests in 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.
  - 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": [
      {
        "code": "code",
        "line": 0,
        "message": "message",
        "param": "param"
      }
    ],
    "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": {
    "completed": 0,
    "failed": 0,
    "total": 0
  },
  "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 your organization's 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[BatchError]]
    - code: Optional[str]
      
      An error code identifying the error type.
    - line: Optional[int]
      
      The line number of the input file where the error occurred, if applicable.
    - message: Optional[str]
      
      A human-readable message providing more details about the error.
    - param: Optional[str]
      
      The name of the parameter that caused the error, if applicable.
  - 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[BatchRequestCounts]
  
  The request counts for different statuses within the batch.
  - completed: int
    
    Number of requests that have been completed successfully.
  - failed: int
    
    Number of requests that have failed.
  - total: int
    
    Total number of requests in 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.
  - 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": [
          {
            "code": "code",
            "line": 0,
            "message": "message",
            "param": "param"
          }
        ],
        "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": {
        "completed": 0,
        "failed": 0,
        "total": 0
      },
      "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[BatchError]]
    - code: Optional[str]
      
      An error code identifying the error type.
    - line: Optional[int]
      
      The line number of the input file where the error occurred, if applicable.
    - message: Optional[str]
      
      A human-readable message providing more details about the error.
    - param: Optional[str]
      
      The name of the parameter that caused the error, if applicable.
  - 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[BatchRequestCounts]
  
  The request counts for different statuses within the batch.
  - completed: int
    
    Number of requests that have been completed successfully.
  - failed: int
    
    Number of requests that have failed.
  - total: int
    
    Total number of requests in 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.
  - 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

class BatchError: …
- code: Optional[str]
  
  An error code identifying the error type.
- line: Optional[int]
  
  The line number of the input file where the error occurred, if applicable.
- message: Optional[str]
  
  A human-readable message providing more details about the error.
- param: Optional[str]
  
  The name of the parameter that caused the error, if applicable.

Batch Request Counts

class BatchRequestCounts: …

The request counts for different statuses within the batch.
- completed: int
  
  Number of requests that have been completed successfully.
- failed: int
  
  Number of requests that have failed.
- total: int
  
  Total number of requests in the batch.

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 +240 −24

6 6

7**post** `/batches`7**post** `/batches`

8 8

~~9Create batch~~9Creates and executes a batch from an uploaded file of requests

10 10

11### Parameters11### Parameters

12 12

133 133

134 - `errors: Optional[Errors]`134 - `errors: Optional[Errors]`

135 135

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

137

138 - `code: Optional[str]`

139

140 An error code identifying the error type.

141

142 - `line: Optional[int]`

143

144 The line number of the input file where the error occurred, if applicable.

145

146 - `message: Optional[str]`

147

148 A human-readable message providing more details about the error.

149

150 - `param: Optional[str]`

151

152 The name of the parameter that caused the error, if applicable.

137 153

138 - `object: Optional[str]`154 - `object: Optional[str]`

139 155

179 195

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

181 197

182 - `request_counts: Optional[object]`198 - `request_counts: Optional[BatchRequestCounts]`

199

200 The request counts for different statuses within the batch.

201

202 - `completed: int`

203

204 Number of requests that have been completed successfully.

205

206 - `failed: int`

207

208 Number of requests that have failed.

209

210 - `total: int`

211

212 Total number of requests in the batch.

183 213

184 - `usage: Optional[BatchUsage]`214 - `usage: Optional[BatchUsage]`

185 215

250 "error_file_id": "error_file_id",280 "error_file_id": "error_file_id",

251 "errors": {281 "errors": {

252 "data": [282 "data": [

253 {}283 {

284 "code": "code",

285 "line": 0,

286 "message": "message",

287 "param": "param"

288 }

254 ],289 ],

255 "object": "object"290 "object": "object"

256 },291 },

264 },299 },

265 "model": "model",300 "model": "model",

266 "output_file_id": "output_file_id",301 "output_file_id": "output_file_id",

267 "request_counts": {},302 "request_counts": {

303 "completed": 0,

304 "failed": 0,

305 "total": 0

306 },

268 "usage": {307 "usage": {

269 "input_tokens": 0,308 "input_tokens": 0,

270 "input_tokens_details": {309 "input_tokens_details": {

332 371

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

334 373

335Retrieve batch374Retrieves a batch.

336 375

337### Parameters376### Parameters

338 377

404 443

405 - `errors: Optional[Errors]`444 - `errors: Optional[Errors]`

406 445

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

447

448 - `code: Optional[str]`

449

450 An error code identifying the error type.

451

452 - `line: Optional[int]`

453

454 The line number of the input file where the error occurred, if applicable.

455

456 - `message: Optional[str]`

457

458 A human-readable message providing more details about the error.

459

460 - `param: Optional[str]`

461

462 The name of the parameter that caused the error, if applicable.

408 463

409 - `object: Optional[str]`464 - `object: Optional[str]`

410 465

450 505

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

452 507

453 - `request_counts: Optional[object]`508 - `request_counts: Optional[BatchRequestCounts]`

509

510 The request counts for different statuses within the batch.

511

512 - `completed: int`

513

514 Number of requests that have been completed successfully.

515

516 - `failed: int`

517

518 Number of requests that have failed.

519

520 - `total: int`

521

522 Total number of requests in the batch.

454 523

455 - `usage: Optional[BatchUsage]`524 - `usage: Optional[BatchUsage]`

456 525

519 "error_file_id": "error_file_id",588 "error_file_id": "error_file_id",

520 "errors": {589 "errors": {

521 "data": [590 "data": [

522 {}591 {

592 "code": "code",

593 "line": 0,

594 "message": "message",

595 "param": "param"

596 }

523 ],597 ],

524 "object": "object"598 "object": "object"

525 },599 },

533 },607 },

534 "model": "model",608 "model": "model",

535 "output_file_id": "output_file_id",609 "output_file_id": "output_file_id",

536 "request_counts": {},610 "request_counts": {

611 "completed": 0,

612 "failed": 0,

613 "total": 0

614 },

537 "usage": {615 "usage": {

538 "input_tokens": 0,616 "input_tokens": 0,

539 "input_tokens_details": {617 "input_tokens_details": {

597 675

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

599 677

600Cancel batch678Cancels an in-progress batch. The batch will be in status `cancelling` for up to 10 minutes, before changing to `cancelled`, where it will have partial results (if any) available in the output file.

601 679

602### Parameters680### Parameters

603 681

669 747

670 - `errors: Optional[Errors]`748 - `errors: Optional[Errors]`

671 749

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

751

752 - `code: Optional[str]`

753

754 An error code identifying the error type.

755

756 - `line: Optional[int]`

757

758 The line number of the input file where the error occurred, if applicable.

759

760 - `message: Optional[str]`

761

762 A human-readable message providing more details about the error.

763

764 - `param: Optional[str]`

765

766 The name of the parameter that caused the error, if applicable.

673 767

674 - `object: Optional[str]`768 - `object: Optional[str]`

675 769

715 809

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

717 811

718 - `request_counts: Optional[object]`812 - `request_counts: Optional[BatchRequestCounts]`

813

814 The request counts for different statuses within the batch.

815

816 - `completed: int`

817

818 Number of requests that have been completed successfully.

819

820 - `failed: int`

821

822 Number of requests that have failed.

823

824 - `total: int`

825

826 Total number of requests in the batch.

719 827

720 - `usage: Optional[BatchUsage]`828 - `usage: Optional[BatchUsage]`

721 829

784 "error_file_id": "error_file_id",892 "error_file_id": "error_file_id",

785 "errors": {893 "errors": {

786 "data": [894 "data": [

787 {}895 {

896 "code": "code",

897 "line": 0,

898 "message": "message",

899 "param": "param"

900 }

788 ],901 ],

789 "object": "object"902 "object": "object"

790 },903 },

798 },911 },

799 "model": "model",912 "model": "model",

800 "output_file_id": "output_file_id",913 "output_file_id": "output_file_id",

801 "request_counts": {},914 "request_counts": {

915 "completed": 0,

916 "failed": 0,

917 "total": 0

918 },

802 "usage": {919 "usage": {

803 "input_tokens": 0,920 "input_tokens": 0,

804 "input_tokens_details": {921 "input_tokens_details": {

862 979

863**get** `/batches`980**get** `/batches`

864 981

865List batches982List your organization's batches.

866 983

867### Parameters984### Parameters

868 985

940 1057

941 - `errors: Optional[Errors]`1058 - `errors: Optional[Errors]`

942 1059

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

1061

1062 - `code: Optional[str]`

1063

1064 An error code identifying the error type.

1065

1066 - `line: Optional[int]`

1067

1068 The line number of the input file where the error occurred, if applicable.

1069

1070 - `message: Optional[str]`

1071

1072 A human-readable message providing more details about the error.

1073

1074 - `param: Optional[str]`

1075

1076 The name of the parameter that caused the error, if applicable.

944 1077

945 - `object: Optional[str]`1078 - `object: Optional[str]`

946 1079

986 1119

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

988 1121

989 - `request_counts: Optional[object]`1122 - `request_counts: Optional[BatchRequestCounts]`

1123

1124 The request counts for different statuses within the batch.

1125

1126 - `completed: int`

1127

1128 Number of requests that have been completed successfully.

1129

1130 - `failed: int`

1131

1132 Number of requests that have failed.

1133

1134 - `total: int`

1135

1136 Total number of requests in the batch.

990 1137

991 - `usage: Optional[BatchUsage]`1138 - `usage: Optional[BatchUsage]`

992 1139

1056 "error_file_id": "error_file_id",1203 "error_file_id": "error_file_id",

1057 "errors": {1204 "errors": {

1058 "data": [1205 "data": [

1059 {}1206 {

1207 "code": "code",

1208 "line": 0,

1209 "message": "message",

1210 "param": "param"

1211 }

1060 ],1212 ],

1061 "object": "object"1213 "object": "object"

1062 },1214 },

1070 },1222 },

1071 "model": "model",1223 "model": "model",

1072 "output_file_id": "output_file_id",1224 "output_file_id": "output_file_id",

1073 "request_counts": {},1225 "request_counts": {

1226 "completed": 0,

1227 "failed": 0,

1228 "total": 0

1229 },

1074 "usage": {1230 "usage": {

1075 "input_tokens": 0,1231 "input_tokens": 0,

1076 "input_tokens_details": {1232 "input_tokens_details": {

1211 1367

1212 - `errors: Optional[Errors]`1368 - `errors: Optional[Errors]`

1213 1369

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

1371

1372 - `code: Optional[str]`

1373

1374 An error code identifying the error type.

1375

1376 - `line: Optional[int]`

1377

1378 The line number of the input file where the error occurred, if applicable.

1379

1380 - `message: Optional[str]`

1381

1382 A human-readable message providing more details about the error.

1383

1384 - `param: Optional[str]`

1385

1386 The name of the parameter that caused the error, if applicable.

1215 1387

1216 - `object: Optional[str]`1388 - `object: Optional[str]`

1217 1389

1257 1429

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

1259 1431

1260 - `request_counts: Optional[object]`1432 - `request_counts: Optional[BatchRequestCounts]`

1433

1434 The request counts for different statuses within the batch.

1435

1436 - `completed: int`

1437

1438 Number of requests that have been completed successfully.

1439

1440 - `failed: int`

1441

1442 Number of requests that have failed.

1443

1444 - `total: int`

1445

1446 Total number of requests in the batch.

1261 1447

1262 - `usage: Optional[BatchUsage]`1448 - `usage: Optional[BatchUsage]`

1263 1449

1296 1482

1297### Batch Error1483### Batch Error

1298 1484

1299- `object`1485- `class BatchError: …`

1486

1487 - `code: Optional[str]`

1488

1489 An error code identifying the error type.

1490

1491 - `line: Optional[int]`

1492

1493 The line number of the input file where the error occurred, if applicable.

1494

1495 - `message: Optional[str]`

1496

1497 A human-readable message providing more details about the error.

1498

1499 - `param: Optional[str]`

1500

1501 The name of the parameter that caused the error, if applicable.

1300 1502

1301### Batch Request Counts1503### Batch Request Counts

1302 1504

1303- `object`1505- `class BatchRequestCounts: …`

1506

1507 The request counts for different statuses within the batch.

1508

1509 - `completed: int`

1510

1511 Number of requests that have been completed successfully.

1512

1513 - `failed: int`

1514

1515 Number of requests that have failed.

1516

1517 - `total: int`

1518

1519 Total number of requests in the batch.

1304 1520

1305### Batch Usage1521### Batch Usage

1306 1522

python/resources/batches/index.md 2026-07-10 23:02 UTC to 2026-07-12 06: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