Batches

Create batch

$ openai batches create

post /batches

Creates and executes a batch from an uploaded file of requests

Parameters

--completion-window: "24h"

The time frame within which the batch should be processed. Currently only 24h is supported.
--endpoint: "/v1/responses" or "/v1/chat/completions" or "/v1/embeddings" or 5 more

The endpoint to be used for all requests in the batch. Currently /v1/responses, /v1/chat/completions, /v1/embeddings, /v1/completions, /v1/moderations, /v1/images/generations, /v1/images/edits, and /v1/videos are supported. Note that /v1/embeddings batches are also restricted to a maximum of 50,000 embedding inputs across all requests in the batch.
--input-file-id: string

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 map[string]

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 object { anchor, seconds }

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

Returns

batch: object { id, completion_window, created_at, 19 more }
- id: string
- completion_window: string
  
  The time frame within which the batch should be processed.
- created_at: number
  
  The Unix timestamp (in seconds) for when the batch was created.
- endpoint: string
  
  The OpenAI API endpoint used by the batch.
- input_file_id: string
  
  The ID of the input file for the batch.
- object: "batch"
  
  The object type, which is always batch.
- status: "validating" or "failed" or "in_progress" or 5 more
  
  The current status of the batch.
  - "validating"
  - "failed"
  - "in_progress"
  - "finalizing"
  - "completed"
  - "expired"
  - "cancelling"
  - "cancelled"
- cancelled_at: optional number
  
  The Unix timestamp (in seconds) for when the batch was cancelled.
- cancelling_at: optional number
  
  The Unix timestamp (in seconds) for when the batch started cancelling.
- completed_at: optional number
  
  The Unix timestamp (in seconds) for when the batch was completed.
- error_file_id: optional string
  
  The ID of the file containing the outputs of requests with errors.
- errors: optional object { data, object }
  - data: optional array of BatchError
    - code: optional string
      
      An error code identifying the error type.
    - line: optional number
      
      The line number of the input file where the error occurred, if applicable.
    - message: optional string
      
      A human-readable message providing more details about the error.
    - param: optional string
      
      The name of the parameter that caused the error, if applicable.
  - object: optional string
    
    The object type, which is always list.
- expired_at: optional number
  
  The Unix timestamp (in seconds) for when the batch expired.
- expires_at: optional number
  
  The Unix timestamp (in seconds) for when the batch will expire.
- failed_at: optional number
  
  The Unix timestamp (in seconds) for when the batch failed.
- finalizing_at: optional number
  
  The Unix timestamp (in seconds) for when the batch started finalizing.
- in_progress_at: optional number
  
  The Unix timestamp (in seconds) for when the batch started processing.
- metadata: optional map[string]
  
  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 string
  
  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 string
  
  The ID of the file containing the outputs of successfully executed requests.
- request_counts: optional object { completed, failed, total }
  
  The request counts for different statuses within the batch.
  - completed: number
    
    Number of requests that have been completed successfully.
  - failed: number
    
    Number of requests that have failed.
  - total: number
    
    Total number of requests in the batch.
- usage: optional object { input_tokens, input_tokens_details, output_tokens, 2 more }
  
  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: number
    
    The number of input tokens.
  - input_tokens_details: object { cached_tokens }
    
    A detailed breakdown of the input tokens.
    - cached_tokens: number
      
      The number of tokens that were retrieved from the cache. More on prompt caching.
  - output_tokens: number
    
    The number of output tokens.
  - output_tokens_details: object { reasoning_tokens }
    
    A detailed breakdown of the output tokens.
    - reasoning_tokens: number
      
      The number of reasoning tokens.
  - total_tokens: number
    
    The total number of tokens used.

Example

openai batches create \
  --api-key 'My API Key' \
  --completion-window 24h \
  --endpoint /v1/responses \
  --input-file-id input_file_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
  }
}

Retrieve batch

$ openai batches retrieve

get /batches/{batch_id}

Retrieves a batch.

Parameters

--batch-id: string

The ID of the batch to retrieve.

Returns

batch: object { id, completion_window, created_at, 19 more }
- id: string
- completion_window: string
  
  The time frame within which the batch should be processed.
- created_at: number
  
  The Unix timestamp (in seconds) for when the batch was created.
- endpoint: string
  
  The OpenAI API endpoint used by the batch.
- input_file_id: string
  
  The ID of the input file for the batch.
- object: "batch"
  
  The object type, which is always batch.
- status: "validating" or "failed" or "in_progress" or 5 more
  
  The current status of the batch.
  - "validating"
  - "failed"
  - "in_progress"
  - "finalizing"
  - "completed"
  - "expired"
  - "cancelling"
  - "cancelled"
- cancelled_at: optional number
  
  The Unix timestamp (in seconds) for when the batch was cancelled.
- cancelling_at: optional number
  
  The Unix timestamp (in seconds) for when the batch started cancelling.
- completed_at: optional number
  
  The Unix timestamp (in seconds) for when the batch was completed.
- error_file_id: optional string
  
  The ID of the file containing the outputs of requests with errors.
- errors: optional object { data, object }
  - data: optional array of BatchError
    - code: optional string
      
      An error code identifying the error type.
    - line: optional number
      
      The line number of the input file where the error occurred, if applicable.
    - message: optional string
      
      A human-readable message providing more details about the error.
    - param: optional string
      
      The name of the parameter that caused the error, if applicable.
  - object: optional string
    
    The object type, which is always list.
- expired_at: optional number
  
  The Unix timestamp (in seconds) for when the batch expired.
- expires_at: optional number
  
  The Unix timestamp (in seconds) for when the batch will expire.
- failed_at: optional number
  
  The Unix timestamp (in seconds) for when the batch failed.
- finalizing_at: optional number
  
  The Unix timestamp (in seconds) for when the batch started finalizing.
- in_progress_at: optional number
  
  The Unix timestamp (in seconds) for when the batch started processing.
- metadata: optional map[string]
  
  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 string
  
  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 string
  
  The ID of the file containing the outputs of successfully executed requests.
- request_counts: optional object { completed, failed, total }
  
  The request counts for different statuses within the batch.
  - completed: number
    
    Number of requests that have been completed successfully.
  - failed: number
    
    Number of requests that have failed.
  - total: number
    
    Total number of requests in the batch.
- usage: optional object { input_tokens, input_tokens_details, output_tokens, 2 more }
  
  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: number
    
    The number of input tokens.
  - input_tokens_details: object { cached_tokens }
    
    A detailed breakdown of the input tokens.
    - cached_tokens: number
      
      The number of tokens that were retrieved from the cache. More on prompt caching.
  - output_tokens: number
    
    The number of output tokens.
  - output_tokens_details: object { reasoning_tokens }
    
    A detailed breakdown of the output tokens.
    - reasoning_tokens: number
      
      The number of reasoning tokens.
  - total_tokens: number
    
    The total number of tokens used.

Example

openai batches retrieve \
  --api-key 'My API Key' \
  --batch-id 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
  }
}

Cancel batch

$ openai batches cancel

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: string

The ID of the batch to cancel.

Returns

batch: object { id, completion_window, created_at, 19 more }
- id: string
- completion_window: string
  
  The time frame within which the batch should be processed.
- created_at: number
  
  The Unix timestamp (in seconds) for when the batch was created.
- endpoint: string
  
  The OpenAI API endpoint used by the batch.
- input_file_id: string
  
  The ID of the input file for the batch.
- object: "batch"
  
  The object type, which is always batch.
- status: "validating" or "failed" or "in_progress" or 5 more
  
  The current status of the batch.
  - "validating"
  - "failed"
  - "in_progress"
  - "finalizing"
  - "completed"
  - "expired"
  - "cancelling"
  - "cancelled"
- cancelled_at: optional number
  
  The Unix timestamp (in seconds) for when the batch was cancelled.
- cancelling_at: optional number
  
  The Unix timestamp (in seconds) for when the batch started cancelling.
- completed_at: optional number
  
  The Unix timestamp (in seconds) for when the batch was completed.
- error_file_id: optional string
  
  The ID of the file containing the outputs of requests with errors.
- errors: optional object { data, object }
  - data: optional array of BatchError
    - code: optional string
      
      An error code identifying the error type.
    - line: optional number
      
      The line number of the input file where the error occurred, if applicable.
    - message: optional string
      
      A human-readable message providing more details about the error.
    - param: optional string
      
      The name of the parameter that caused the error, if applicable.
  - object: optional string
    
    The object type, which is always list.
- expired_at: optional number
  
  The Unix timestamp (in seconds) for when the batch expired.
- expires_at: optional number
  
  The Unix timestamp (in seconds) for when the batch will expire.
- failed_at: optional number
  
  The Unix timestamp (in seconds) for when the batch failed.
- finalizing_at: optional number
  
  The Unix timestamp (in seconds) for when the batch started finalizing.
- in_progress_at: optional number
  
  The Unix timestamp (in seconds) for when the batch started processing.
- metadata: optional map[string]
  
  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 string
  
  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 string
  
  The ID of the file containing the outputs of successfully executed requests.
- request_counts: optional object { completed, failed, total }
  
  The request counts for different statuses within the batch.
  - completed: number
    
    Number of requests that have been completed successfully.
  - failed: number
    
    Number of requests that have failed.
  - total: number
    
    Total number of requests in the batch.
- usage: optional object { input_tokens, input_tokens_details, output_tokens, 2 more }
  
  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: number
    
    The number of input tokens.
  - input_tokens_details: object { cached_tokens }
    
    A detailed breakdown of the input tokens.
    - cached_tokens: number
      
      The number of tokens that were retrieved from the cache. More on prompt caching.
  - output_tokens: number
    
    The number of output tokens.
  - output_tokens_details: object { reasoning_tokens }
    
    A detailed breakdown of the output tokens.
    - reasoning_tokens: number
      
      The number of reasoning tokens.
  - total_tokens: number
    
    The total number of tokens used.

Example

openai batches cancel \
  --api-key 'My API Key' \
  --batch-id 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
  }
}

List batches

$ openai batches list

get /batches

List your organization's batches.

Parameters

--after: optional string

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 number

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

Returns

ListBatchesResponse: object { data, has_more, object, 2 more }
- data: array of Batch
  - id: string
  - completion_window: string
    
    The time frame within which the batch should be processed.
  - created_at: number
    
    The Unix timestamp (in seconds) for when the batch was created.
  - endpoint: string
    
    The OpenAI API endpoint used by the batch.
  - input_file_id: string
    
    The ID of the input file for the batch.
  - object: "batch"
    
    The object type, which is always batch.
  - status: "validating" or "failed" or "in_progress" or 5 more
    
    The current status of the batch.
    - "validating"
    - "failed"
    - "in_progress"
    - "finalizing"
    - "completed"
    - "expired"
    - "cancelling"
    - "cancelled"
  - cancelled_at: optional number
    
    The Unix timestamp (in seconds) for when the batch was cancelled.
  - cancelling_at: optional number
    
    The Unix timestamp (in seconds) for when the batch started cancelling.
  - completed_at: optional number
    
    The Unix timestamp (in seconds) for when the batch was completed.
  - error_file_id: optional string
    
    The ID of the file containing the outputs of requests with errors.
  - errors: optional object { data, object }
    - data: optional array of BatchError
      - code: optional string
        
        An error code identifying the error type.
      - line: optional number
        
        The line number of the input file where the error occurred, if applicable.
      - message: optional string
        
        A human-readable message providing more details about the error.
      - param: optional string
        
        The name of the parameter that caused the error, if applicable.
    - object: optional string
      
      The object type, which is always list.
  - expired_at: optional number
    
    The Unix timestamp (in seconds) for when the batch expired.
  - expires_at: optional number
    
    The Unix timestamp (in seconds) for when the batch will expire.
  - failed_at: optional number
    
    The Unix timestamp (in seconds) for when the batch failed.
  - finalizing_at: optional number
    
    The Unix timestamp (in seconds) for when the batch started finalizing.
  - in_progress_at: optional number
    
    The Unix timestamp (in seconds) for when the batch started processing.
  - metadata: optional map[string]
    
    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 string
    
    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 string
    
    The ID of the file containing the outputs of successfully executed requests.
  - request_counts: optional object { completed, failed, total }
    
    The request counts for different statuses within the batch.
    - completed: number
      
      Number of requests that have been completed successfully.
    - failed: number
      
      Number of requests that have failed.
    - total: number
      
      Total number of requests in the batch.
  - usage: optional object { input_tokens, input_tokens_details, output_tokens, 2 more }
    
    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: number
      
      The number of input tokens.
    - input_tokens_details: object { cached_tokens }
      
      A detailed breakdown of the input tokens.
      - cached_tokens: number
        
        The number of tokens that were retrieved from the cache. More on prompt caching.
    - output_tokens: number
      
      The number of output tokens.
    - output_tokens_details: object { reasoning_tokens }
      
      A detailed breakdown of the output tokens.
      - reasoning_tokens: number
        
        The number of reasoning tokens.
    - total_tokens: number
      
      The total number of tokens used.
- has_more: boolean
- object: "list"
- first_id: optional string
- last_id: optional string

Example

openai batches list \
  --api-key 'My API Key'

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

Domain Types

Batch

batch: object { id, completion_window, created_at, 19 more }
- id: string
- completion_window: string
  
  The time frame within which the batch should be processed.
- created_at: number
  
  The Unix timestamp (in seconds) for when the batch was created.
- endpoint: string
  
  The OpenAI API endpoint used by the batch.
- input_file_id: string
  
  The ID of the input file for the batch.
- object: "batch"
  
  The object type, which is always batch.
- status: "validating" or "failed" or "in_progress" or 5 more
  
  The current status of the batch.
  - "validating"
  - "failed"
  - "in_progress"
  - "finalizing"
  - "completed"
  - "expired"
  - "cancelling"
  - "cancelled"
- cancelled_at: optional number
  
  The Unix timestamp (in seconds) for when the batch was cancelled.
- cancelling_at: optional number
  
  The Unix timestamp (in seconds) for when the batch started cancelling.
- completed_at: optional number
  
  The Unix timestamp (in seconds) for when the batch was completed.
- error_file_id: optional string
  
  The ID of the file containing the outputs of requests with errors.
- errors: optional object { data, object }
  - data: optional array of BatchError
    - code: optional string
      
      An error code identifying the error type.
    - line: optional number
      
      The line number of the input file where the error occurred, if applicable.
    - message: optional string
      
      A human-readable message providing more details about the error.
    - param: optional string
      
      The name of the parameter that caused the error, if applicable.
  - object: optional string
    
    The object type, which is always list.
- expired_at: optional number
  
  The Unix timestamp (in seconds) for when the batch expired.
- expires_at: optional number
  
  The Unix timestamp (in seconds) for when the batch will expire.
- failed_at: optional number
  
  The Unix timestamp (in seconds) for when the batch failed.
- finalizing_at: optional number
  
  The Unix timestamp (in seconds) for when the batch started finalizing.
- in_progress_at: optional number
  
  The Unix timestamp (in seconds) for when the batch started processing.
- metadata: optional map[string]
  
  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 string
  
  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 string
  
  The ID of the file containing the outputs of successfully executed requests.
- request_counts: optional object { completed, failed, total }
  
  The request counts for different statuses within the batch.
  - completed: number
    
    Number of requests that have been completed successfully.
  - failed: number
    
    Number of requests that have failed.
  - total: number
    
    Total number of requests in the batch.
- usage: optional object { input_tokens, input_tokens_details, output_tokens, 2 more }
  
  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: number
    
    The number of input tokens.
  - input_tokens_details: object { cached_tokens }
    
    A detailed breakdown of the input tokens.
    - cached_tokens: number
      
      The number of tokens that were retrieved from the cache. More on prompt caching.
  - output_tokens: number
    
    The number of output tokens.
  - output_tokens_details: object { reasoning_tokens }
    
    A detailed breakdown of the output tokens.
    - reasoning_tokens: number
      
      The number of reasoning tokens.
  - total_tokens: number
    
    The total number of tokens used.

Batch Error

batch_error: object { code, line, message, param }
- code: optional string
  
  An error code identifying the error type.
- line: optional number
  
  The line number of the input file where the error occurred, if applicable.
- message: optional string
  
  A human-readable message providing more details about the error.
- param: optional string
  
  The name of the parameter that caused the error, if applicable.

Batch Request Counts

batch_request_counts: object { completed, failed, total }

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

Batch Usage

batch_usage: object { input_tokens, input_tokens_details, output_tokens, 2 more }

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

cli/resources/batches/index.md +1319 −0 created

1# Batches

3## Create batch

5`$ openai batches create`

7**post** `/batches`

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

11### Parameters

13- `--completion-window: "24h"`

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

17- `--endpoint: "/v1/responses" or "/v1/chat/completions" or "/v1/embeddings" or 5 more`

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

21- `--input-file-id: string`

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

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

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

29- `--metadata: optional map[string]`

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

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

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

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

36 with a maximum length of 512 characters.

38- `--output-expires-after: optional object { anchor, seconds }`

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

42### Returns

44- `batch: object { id, completion_window, created_at, 19 more }`

46 - `id: string`

48 - `completion_window: string`

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

52 - `created_at: number`

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

56 - `endpoint: string`

58 The OpenAI API endpoint used by the batch.

60 - `input_file_id: string`

62 The ID of the input file for the batch.

64 - `object: "batch"`

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

68 - `status: "validating" or "failed" or "in_progress" or 5 more`

70 The current status of the batch.

72 - `"validating"`

74 - `"failed"`

76 - `"in_progress"`

78 - `"finalizing"`

80 - `"completed"`

82 - `"expired"`

84 - `"cancelling"`

86 - `"cancelled"`

88 - `cancelled_at: optional number`

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

92 - `cancelling_at: optional number`

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

96 - `completed_at: optional number`

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

100 - `error_file_id: optional string`

101

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

103

104 - `errors: optional object { data, object }`

105

106 - `data: optional array of BatchError`

107

108 - `code: optional string`

109

110 An error code identifying the error type.

111

112 - `line: optional number`

113

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

115

116 - `message: optional string`

117

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

119

120 - `param: optional string`

121

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

123

124 - `object: optional string`

125

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

127

128 - `expired_at: optional number`

129

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

131

132 - `expires_at: optional number`

133

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

135

136 - `failed_at: optional number`

137

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

139

140 - `finalizing_at: optional number`

141

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

143

144 - `in_progress_at: optional number`

145

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

147

148 - `metadata: optional map[string]`

149

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

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

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

153

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

155 with a maximum length of 512 characters.

156

157 - `model: optional string`

158

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

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

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

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

163

164 - `output_file_id: optional string`

165

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

167

168 - `request_counts: optional object { completed, failed, total }`

169

170 The request counts for different statuses within the batch.

171

172 - `completed: number`

173

174 Number of requests that have been completed successfully.

175

176 - `failed: number`

177

178 Number of requests that have failed.

179

180 - `total: number`

181

182 Total number of requests in the batch.

183

184 - `usage: optional object { input_tokens, input_tokens_details, output_tokens, 2 more }`

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: number`

191

192 The number of input tokens.

193

194 - `input_tokens_details: object { cached_tokens }`

195

196 A detailed breakdown of the input tokens.

197

198 - `cached_tokens: number`

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: number`

204

205 The number of output tokens.

206

207 - `output_tokens_details: object { reasoning_tokens }`

208

209 A detailed breakdown of the output tokens.

210

211 - `reasoning_tokens: number`

212

213 The number of reasoning tokens.

214

215 - `total_tokens: number`

216

217 The total number of tokens used.

218

219### Example

220

221```cli

222openai batches create \

223 --api-key 'My API Key' \

224 --completion-window 24h \

225 --endpoint /v1/responses \

226 --input-file-id input_file_id

227```

228

229#### Response

230

231```json

232{

233 "id": "id",

234 "completion_window": "completion_window",

235 "created_at": 0,

236 "endpoint": "endpoint",

237 "input_file_id": "input_file_id",

238 "object": "batch",

239 "status": "validating",

240 "cancelled_at": 0,

241 "cancelling_at": 0,

242 "completed_at": 0,

243 "error_file_id": "error_file_id",

244 "errors": {

245 "data": [

246 {

247 "code": "code",

248 "line": 0,

249 "message": "message",

250 "param": "param"

251 }

252 ],

253 "object": "object"

254 },

255 "expired_at": 0,

256 "expires_at": 0,

257 "failed_at": 0,

258 "finalizing_at": 0,

259 "in_progress_at": 0,

260 "metadata": {

261 "foo": "string"

262 },

263 "model": "model",

264 "output_file_id": "output_file_id",

265 "request_counts": {

266 "completed": 0,

267 "failed": 0,

268 "total": 0

269 },

270 "usage": {

271 "input_tokens": 0,

272 "input_tokens_details": {

273 "cached_tokens": 0

274 },

275 "output_tokens": 0,

276 "output_tokens_details": {

277 "reasoning_tokens": 0

278 },

279 "total_tokens": 0

280 }

281}

282```

283

284## Retrieve batch

285

286`$ openai batches retrieve`

287

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

289

290Retrieves a batch.

291

292### Parameters

293

294- `--batch-id: string`

295

296 The ID of the batch to retrieve.

297

298### Returns

299

300- `batch: object { id, completion_window, created_at, 19 more }`

301

302 - `id: string`

303

304 - `completion_window: string`

305

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

307

308 - `created_at: number`

309

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

311

312 - `endpoint: string`

313

314 The OpenAI API endpoint used by the batch.

315

316 - `input_file_id: string`

317

318 The ID of the input file for the batch.

319

320 - `object: "batch"`

321

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

323

324 - `status: "validating" or "failed" or "in_progress" or 5 more`

325

326 The current status of the batch.

327

328 - `"validating"`

329

330 - `"failed"`

331

332 - `"in_progress"`

333

334 - `"finalizing"`

335

336 - `"completed"`

337

338 - `"expired"`

339

340 - `"cancelling"`

341

342 - `"cancelled"`

343

344 - `cancelled_at: optional number`

345

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

347

348 - `cancelling_at: optional number`

349

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

351

352 - `completed_at: optional number`

353

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

355

356 - `error_file_id: optional string`

357

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

359

360 - `errors: optional object { data, object }`

361

362 - `data: optional array of BatchError`

363

364 - `code: optional string`

365

366 An error code identifying the error type.

367

368 - `line: optional number`

369

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

371

372 - `message: optional string`

373

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

375

376 - `param: optional string`

377

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

379

380 - `object: optional string`

381

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

383

384 - `expired_at: optional number`

385

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

387

388 - `expires_at: optional number`

389

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

391

392 - `failed_at: optional number`

393

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

395

396 - `finalizing_at: optional number`

397

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

399

400 - `in_progress_at: optional number`

401

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

403

404 - `metadata: optional map[string]`

405

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

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

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

409

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

411 with a maximum length of 512 characters.

412

413 - `model: optional string`

414

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

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

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

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

419

420 - `output_file_id: optional string`

421

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

423

424 - `request_counts: optional object { completed, failed, total }`

425

426 The request counts for different statuses within the batch.

427

428 - `completed: number`

429

430 Number of requests that have been completed successfully.

431

432 - `failed: number`

433

434 Number of requests that have failed.

435

436 - `total: number`

437

438 Total number of requests in the batch.

439

440 - `usage: optional object { input_tokens, input_tokens_details, output_tokens, 2 more }`

441

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

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

444 batches created after September 7, 2025.

445

446 - `input_tokens: number`

447

448 The number of input tokens.

449

450 - `input_tokens_details: object { cached_tokens }`

451

452 A detailed breakdown of the input tokens.

453

454 - `cached_tokens: number`

455

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

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

458

459 - `output_tokens: number`

460

461 The number of output tokens.

462

463 - `output_tokens_details: object { reasoning_tokens }`

464

465 A detailed breakdown of the output tokens.

466

467 - `reasoning_tokens: number`

468

469 The number of reasoning tokens.

470

471 - `total_tokens: number`

472

473 The total number of tokens used.

474

475### Example

476

477```cli

478openai batches retrieve \

479 --api-key 'My API Key' \

480 --batch-id batch_id

481```

482

483#### Response

484

485```json

486{

487 "id": "id",

488 "completion_window": "completion_window",

489 "created_at": 0,

490 "endpoint": "endpoint",

491 "input_file_id": "input_file_id",

492 "object": "batch",

493 "status": "validating",

494 "cancelled_at": 0,

495 "cancelling_at": 0,

496 "completed_at": 0,

497 "error_file_id": "error_file_id",

498 "errors": {

499 "data": [

500 {

501 "code": "code",

502 "line": 0,

503 "message": "message",

504 "param": "param"

505 }

506 ],

507 "object": "object"

508 },

509 "expired_at": 0,

510 "expires_at": 0,

511 "failed_at": 0,

512 "finalizing_at": 0,

513 "in_progress_at": 0,

514 "metadata": {

515 "foo": "string"

516 },

517 "model": "model",

518 "output_file_id": "output_file_id",

519 "request_counts": {

520 "completed": 0,

521 "failed": 0,

522 "total": 0

523 },

524 "usage": {

525 "input_tokens": 0,

526 "input_tokens_details": {

527 "cached_tokens": 0

528 },

529 "output_tokens": 0,

530 "output_tokens_details": {

531 "reasoning_tokens": 0

532 },

533 "total_tokens": 0

534 }

535}

536```

537

538## Cancel batch

539

540`$ openai batches cancel`

541

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

543

544Cancels 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.

545

546### Parameters

547

548- `--batch-id: string`

549

550 The ID of the batch to cancel.

551

552### Returns

553

554- `batch: object { id, completion_window, created_at, 19 more }`

555

556 - `id: string`

557

558 - `completion_window: string`

559

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

561

562 - `created_at: number`

563

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

565

566 - `endpoint: string`

567

568 The OpenAI API endpoint used by the batch.

569

570 - `input_file_id: string`

571

572 The ID of the input file for the batch.

573

574 - `object: "batch"`

575

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

577

578 - `status: "validating" or "failed" or "in_progress" or 5 more`

579

580 The current status of the batch.

581

582 - `"validating"`

583

584 - `"failed"`

585

586 - `"in_progress"`

587

588 - `"finalizing"`

589

590 - `"completed"`

591

592 - `"expired"`

593

594 - `"cancelling"`

595

596 - `"cancelled"`

597

598 - `cancelled_at: optional number`

599

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

601

602 - `cancelling_at: optional number`

603

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

605

606 - `completed_at: optional number`

607

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

609

610 - `error_file_id: optional string`

611

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

613

614 - `errors: optional object { data, object }`

615

616 - `data: optional array of BatchError`

617

618 - `code: optional string`

619

620 An error code identifying the error type.

621

622 - `line: optional number`

623

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

625

626 - `message: optional string`

627

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

629

630 - `param: optional string`

631

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

633

634 - `object: optional string`

635

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

637

638 - `expired_at: optional number`

639

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

641

642 - `expires_at: optional number`

643

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

645

646 - `failed_at: optional number`

647

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

649

650 - `finalizing_at: optional number`

651

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

653

654 - `in_progress_at: optional number`

655

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

657

658 - `metadata: optional map[string]`

659

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

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

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

663

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

665 with a maximum length of 512 characters.

666

667 - `model: optional string`

668

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

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

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

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

673

674 - `output_file_id: optional string`

675

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

677

678 - `request_counts: optional object { completed, failed, total }`

679

680 The request counts for different statuses within the batch.

681

682 - `completed: number`

683

684 Number of requests that have been completed successfully.

685

686 - `failed: number`

687

688 Number of requests that have failed.

689

690 - `total: number`

691

692 Total number of requests in the batch.

693

694 - `usage: optional object { input_tokens, input_tokens_details, output_tokens, 2 more }`

695

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

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

698 batches created after September 7, 2025.

699

700 - `input_tokens: number`

701

702 The number of input tokens.

703

704 - `input_tokens_details: object { cached_tokens }`

705

706 A detailed breakdown of the input tokens.

707

708 - `cached_tokens: number`

709

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

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

712

713 - `output_tokens: number`

714

715 The number of output tokens.

716

717 - `output_tokens_details: object { reasoning_tokens }`

718

719 A detailed breakdown of the output tokens.

720

721 - `reasoning_tokens: number`

722

723 The number of reasoning tokens.

724

725 - `total_tokens: number`

726

727 The total number of tokens used.

728

729### Example

730

731```cli

732openai batches cancel \

733 --api-key 'My API Key' \

734 --batch-id batch_id

735```

736

737#### Response

738

739```json

740{

741 "id": "id",

742 "completion_window": "completion_window",

743 "created_at": 0,

744 "endpoint": "endpoint",

745 "input_file_id": "input_file_id",

746 "object": "batch",

747 "status": "validating",

748 "cancelled_at": 0,

749 "cancelling_at": 0,

750 "completed_at": 0,

751 "error_file_id": "error_file_id",

752 "errors": {

753 "data": [

754 {

755 "code": "code",

756 "line": 0,

757 "message": "message",

758 "param": "param"

759 }

760 ],

761 "object": "object"

762 },

763 "expired_at": 0,

764 "expires_at": 0,

765 "failed_at": 0,

766 "finalizing_at": 0,

767 "in_progress_at": 0,

768 "metadata": {

769 "foo": "string"

770 },

771 "model": "model",

772 "output_file_id": "output_file_id",

773 "request_counts": {

774 "completed": 0,

775 "failed": 0,

776 "total": 0

777 },

778 "usage": {

779 "input_tokens": 0,

780 "input_tokens_details": {

781 "cached_tokens": 0

782 },

783 "output_tokens": 0,

784 "output_tokens_details": {

785 "reasoning_tokens": 0

786 },

787 "total_tokens": 0

788 }

789}

790```

791

792## List batches

793

794`$ openai batches list`

795

796**get** `/batches`

797

798List your organization's batches.

799

800### Parameters

801

802- `--after: optional string`

803

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

805

806- `--limit: optional number`

807

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

809

810### Returns

811

812- `ListBatchesResponse: object { data, has_more, object, 2 more }`

813

814 - `data: array of Batch`

815

816 - `id: string`

817

818 - `completion_window: string`

819

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

821

822 - `created_at: number`

823

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

825

826 - `endpoint: string`

827

828 The OpenAI API endpoint used by the batch.

829

830 - `input_file_id: string`

831

832 The ID of the input file for the batch.

833

834 - `object: "batch"`

835

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

837

838 - `status: "validating" or "failed" or "in_progress" or 5 more`

839

840 The current status of the batch.

841

842 - `"validating"`

843

844 - `"failed"`

845

846 - `"in_progress"`

847

848 - `"finalizing"`

849

850 - `"completed"`

851

852 - `"expired"`

853

854 - `"cancelling"`

855

856 - `"cancelled"`

857

858 - `cancelled_at: optional number`

859

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

861

862 - `cancelling_at: optional number`

863

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

865

866 - `completed_at: optional number`

867

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

869

870 - `error_file_id: optional string`

871

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

873

874 - `errors: optional object { data, object }`

875

876 - `data: optional array of BatchError`

877

878 - `code: optional string`

879

880 An error code identifying the error type.

881

882 - `line: optional number`

883

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

885

886 - `message: optional string`

887

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

889

890 - `param: optional string`

891

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

893

894 - `object: optional string`

895

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

897

898 - `expired_at: optional number`

899

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

901

902 - `expires_at: optional number`

903

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

905

906 - `failed_at: optional number`

907

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

909

910 - `finalizing_at: optional number`

911

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

913

914 - `in_progress_at: optional number`

915

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

917

918 - `metadata: optional map[string]`

919

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

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

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

923

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

925 with a maximum length of 512 characters.

926

927 - `model: optional string`

928

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

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

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

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

933

934 - `output_file_id: optional string`

935

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

937

938 - `request_counts: optional object { completed, failed, total }`

939

940 The request counts for different statuses within the batch.

941

942 - `completed: number`

943

944 Number of requests that have been completed successfully.

945

946 - `failed: number`

947

948 Number of requests that have failed.

949

950 - `total: number`

951

952 Total number of requests in the batch.

953

954 - `usage: optional object { input_tokens, input_tokens_details, output_tokens, 2 more }`

955

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

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

958 batches created after September 7, 2025.

959

960 - `input_tokens: number`

961

962 The number of input tokens.

963

964 - `input_tokens_details: object { cached_tokens }`

965

966 A detailed breakdown of the input tokens.

967

968 - `cached_tokens: number`

969

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

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

972

973 - `output_tokens: number`

974

975 The number of output tokens.

976

977 - `output_tokens_details: object { reasoning_tokens }`

978

979 A detailed breakdown of the output tokens.

980

981 - `reasoning_tokens: number`

982

983 The number of reasoning tokens.

984

985 - `total_tokens: number`

986

987 The total number of tokens used.

988

989 - `has_more: boolean`

990

991 - `object: "list"`

992

993 - `first_id: optional string`

994

995 - `last_id: optional string`

996

997### Example

998

999```cli

1000openai batches list \

1001 --api-key 'My API Key'

1002```

1003

1004#### Response

1005

1006```json

1007{

1008 "data": [

1009 {

1010 "id": "id",

1011 "completion_window": "completion_window",

1012 "created_at": 0,

1013 "endpoint": "endpoint",

1014 "input_file_id": "input_file_id",

1015 "object": "batch",

1016 "status": "validating",

1017 "cancelled_at": 0,

1018 "cancelling_at": 0,

1019 "completed_at": 0,

1020 "error_file_id": "error_file_id",

1021 "errors": {

1022 "data": [

1023 {

1024 "code": "code",

1025 "line": 0,

1026 "message": "message",

1027 "param": "param"

1028 }

1029 ],

1030 "object": "object"

1031 },

1032 "expired_at": 0,

1033 "expires_at": 0,

1034 "failed_at": 0,

1035 "finalizing_at": 0,

1036 "in_progress_at": 0,

1037 "metadata": {

1038 "foo": "string"

1039 },

1040 "model": "model",

1041 "output_file_id": "output_file_id",

1042 "request_counts": {

1043 "completed": 0,

1044 "failed": 0,

1045 "total": 0

1046 },

1047 "usage": {

1048 "input_tokens": 0,

1049 "input_tokens_details": {

1050 "cached_tokens": 0

1051 },

1052 "output_tokens": 0,

1053 "output_tokens_details": {

1054 "reasoning_tokens": 0

1055 },

1056 "total_tokens": 0

1057 }

1058 }

1059 ],

1060 "has_more": true,

1061 "object": "list",

1062 "first_id": "batch_abc123",

1063 "last_id": "batch_abc456"

1064}

1065```

1066

1067## Domain Types

1068

1069### Batch

1070

1071- `batch: object { id, completion_window, created_at, 19 more }`

1072

1073 - `id: string`

1074

1075 - `completion_window: string`

1076

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

1078

1079 - `created_at: number`

1080

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

1082

1083 - `endpoint: string`

1084

1085 The OpenAI API endpoint used by the batch.

1086

1087 - `input_file_id: string`

1088

1089 The ID of the input file for the batch.

1090

1091 - `object: "batch"`

1092

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

1094

1095 - `status: "validating" or "failed" or "in_progress" or 5 more`

1096

1097 The current status of the batch.

1098

1099 - `"validating"`

1100

1101 - `"failed"`

1102

1103 - `"in_progress"`

1104

1105 - `"finalizing"`

1106

1107 - `"completed"`

1108

1109 - `"expired"`

1110

1111 - `"cancelling"`

1112

1113 - `"cancelled"`

1114

1115 - `cancelled_at: optional number`

1116

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

1118

1119 - `cancelling_at: optional number`

1120

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

1122

1123 - `completed_at: optional number`

1124

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

1126

1127 - `error_file_id: optional string`

1128

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

1130

1131 - `errors: optional object { data, object }`

1132

1133 - `data: optional array of BatchError`

1134

1135 - `code: optional string`

1136

1137 An error code identifying the error type.

1138

1139 - `line: optional number`

1140

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

1142

1143 - `message: optional string`

1144

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

1146

1147 - `param: optional string`

1148

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

1150

1151 - `object: optional string`

1152

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

1154

1155 - `expired_at: optional number`

1156

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

1158

1159 - `expires_at: optional number`

1160

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

1162

1163 - `failed_at: optional number`

1164

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

1166

1167 - `finalizing_at: optional number`

1168

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

1170

1171 - `in_progress_at: optional number`

1172

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

1174

1175 - `metadata: optional map[string]`

1176

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

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

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

1180

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

1182 with a maximum length of 512 characters.

1183

1184 - `model: optional string`

1185

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

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

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

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

1190

1191 - `output_file_id: optional string`

1192

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

1194

1195 - `request_counts: optional object { completed, failed, total }`

1196

1197 The request counts for different statuses within the batch.

1198

1199 - `completed: number`

1200

1201 Number of requests that have been completed successfully.

1202

1203 - `failed: number`

1204

1205 Number of requests that have failed.

1206

1207 - `total: number`

1208

1209 Total number of requests in the batch.

1210

1211 - `usage: optional object { input_tokens, input_tokens_details, output_tokens, 2 more }`

1212

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

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

1215 batches created after September 7, 2025.

1216

1217 - `input_tokens: number`

1218

1219 The number of input tokens.

1220

1221 - `input_tokens_details: object { cached_tokens }`

1222

1223 A detailed breakdown of the input tokens.

1224

1225 - `cached_tokens: number`

1226

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

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

1229

1230 - `output_tokens: number`

1231

1232 The number of output tokens.

1233

1234 - `output_tokens_details: object { reasoning_tokens }`

1235

1236 A detailed breakdown of the output tokens.

1237

1238 - `reasoning_tokens: number`

1239

1240 The number of reasoning tokens.

1241

1242 - `total_tokens: number`

1243

1244 The total number of tokens used.

1245

1246### Batch Error

1247

1248- `batch_error: object { code, line, message, param }`

1249

1250 - `code: optional string`

1251

1252 An error code identifying the error type.

1253

1254 - `line: optional number`

1255

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

1257

1258 - `message: optional string`

1259

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

1261

1262 - `param: optional string`

1263

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

1265

1266### Batch Request Counts

1267

1268- `batch_request_counts: object { completed, failed, total }`

1269

1270 The request counts for different statuses within the batch.

1271

1272 - `completed: number`

1273

1274 Number of requests that have been completed successfully.

1275

1276 - `failed: number`

1277

1278 Number of requests that have failed.

1279

1280 - `total: number`

1281

1282 Total number of requests in the batch.

1283

1284### Batch Usage

1285

1286- `batch_usage: object { input_tokens, input_tokens_details, output_tokens, 2 more }`

1287

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

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

1290 batches created after September 7, 2025.

1291

1292 - `input_tokens: number`

1293

1294 The number of input tokens.

1295

1296 - `input_tokens_details: object { cached_tokens }`

1297

1298 A detailed breakdown of the input tokens.

1299

1300 - `cached_tokens: number`

1301

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

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

1304

1305 - `output_tokens: number`

1306

1307 The number of output tokens.

1308

1309 - `output_tokens_details: object { reasoning_tokens }`

1310

1311 A detailed breakdown of the output tokens.

1312

1313 - `reasoning_tokens: number`

1314

1315 The number of reasoning tokens.

1316

1317 - `total_tokens: number`

1318

1319 The total number of tokens used.

cli/resources/batches/index.md 2026-05-05 23:00 UTC to 2026-05-07 21:57 UTC

Batches

Create batch

Parameters

Returns

Example

Response

Retrieve batch

Parameters

Returns

Example

Response

Cancel batch

Parameters

Returns

Example

Response

List batches

Parameters

Returns

Example

Response

Domain Types

Batch

Batch Error

Batch Request Counts

Batch Usage