Batches

Create batch

post /batches

Create batch

Body Parameters

completion_window: "24h"

The time frame within which the batch should be processed. Currently only 24h is supported.
- "24h"
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.
- "/v1/responses"
- "/v1/chat/completions"
- "/v1/embeddings"
- "/v1/completions"
- "/v1/moderations"
- "/v1/images/generations"
- "/v1/images/edits"
- "/v1/videos"
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 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 object { anchor, seconds }

The expiration policy for the output and/or error file that are generated for a batch.
- anchor: "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: number
  
  The number of seconds after the anchor time that the file will expire. Must be between 3600 (1 hour) and 2592000 (30 days).

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.
  - "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 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 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 BatchRequestCounts
  
  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 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: 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

curl https://api.openai.com/v1/batches \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $OPENAI_API_KEY" \
    -d '{
          "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
  }
}

Example

curl https://api.openai.com/v1/batches \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "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

get /batches/{batch_id}

Retrieve batch

Path Parameters

batch_id: string

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.
  - "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 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 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 BatchRequestCounts
  
  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 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: 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

curl https://api.openai.com/v1/batches/$BATCH_ID \
    -H "Authorization: Bearer $OPENAI_API_KEY"

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

curl https://api.openai.com/v1/batches/batch_abc123 \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \

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

post /batches/{batch_id}/cancel

Cancel batch

Path Parameters

batch_id: string

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.
  - "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 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 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 BatchRequestCounts
  
  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 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: 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

curl https://api.openai.com/v1/batches/$BATCH_ID/cancel \
    -X POST \
    -H "Authorization: Bearer $OPENAI_API_KEY"

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

curl https://api.openai.com/v1/batches/batch_abc123/cancel \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -X POST

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

get /batches

List batches

Query 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

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.
  - "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 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 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 BatchRequestCounts
  
  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 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: 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"
- "list"
first_id: optional string
last_id: optional string

Example

curl https://api.openai.com/v1/batches \
    -H "Authorization: Bearer $OPENAI_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"
}

Example

curl https://api.openai.com/v1/batches?limit=2 \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json"

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

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.
  - "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 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 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 BatchRequestCounts
  
  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 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: 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

BatchError 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

BatchRequestCounts 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

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

resources/batches/index.md +65 −27

4 4

5**post** `/batches`5**post** `/batches`

6 6

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

8 8

9### Body Parameters9### Body Parameters

10 10

38 38

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

40 40

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

42 42

43 Your input file must be formatted as a [JSONL file](/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.43 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.

44 44

45- `metadata: optional Metadata`45- `metadata: optional Metadata`

46 46

131 131

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

133 133

134 - `data: optional array of object { code, line, message, param }`134 - `data: optional array of BatchError`

135 135

136 - `code: optional string`136 - `code: optional string`

137 137

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

188 offers a wide range of models with different capabilities, performance188 offers a wide range of models with different capabilities, performance

189 characteristics, and price points. Refer to the [model189 characteristics, and price points. Refer to the [model

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

191 191

192 - `output_file_id: optional string`192 - `output_file_id: optional string`

193 193

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

195 195

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

197 197

198 The request counts for different statuses within the batch.198 The request counts for different statuses within the batch.

199 199

226 - `cached_tokens: number`226 - `cached_tokens: number`

227 227

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

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

230 230

231 - `output_tokens: number`231 - `output_tokens: number`

232 232

363 363

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

365 365

366Retrieves a batch.366Retrieve batch

367 367

368### Path Parameters368### Path Parameters

369 369

435 435

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

437 437

438 - `data: optional array of object { code, line, message, param }`438 - `data: optional array of BatchError`

439 439

440 - `code: optional string`440 - `code: optional string`

441 441

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

492 offers a wide range of models with different capabilities, performance492 offers a wide range of models with different capabilities, performance

493 characteristics, and price points. Refer to the [model493 characteristics, and price points. Refer to the [model

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

495 495

496 - `output_file_id: optional string`496 - `output_file_id: optional string`

497 497

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

499 499

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

501 501

502 The request counts for different statuses within the batch.502 The request counts for different statuses within the batch.

503 503

530 - `cached_tokens: number`530 - `cached_tokens: number`

531 531

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

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

534 534

535 - `output_tokens: number`535 - `output_tokens: number`

536 536

656 656

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

658 658

659Cancels 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.659Cancel batch

660 660

661### Path Parameters661### Path Parameters

662 662

728 728

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

730 730

731 - `data: optional array of object { code, line, message, param }`731 - `data: optional array of BatchError`

732 732

733 - `code: optional string`733 - `code: optional string`

734 734

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

785 offers a wide range of models with different capabilities, performance785 offers a wide range of models with different capabilities, performance

786 characteristics, and price points. Refer to the [model786 characteristics, and price points. Refer to the [model

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

788 788

789 - `output_file_id: optional string`789 - `output_file_id: optional string`

790 790

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

792 792

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

794 794

795 The request counts for different statuses within the batch.795 The request counts for different statuses within the batch.

796 796

823 - `cached_tokens: number`823 - `cached_tokens: number`

824 824

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

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

827 827

828 - `output_tokens: number`828 - `output_tokens: number`

829 829

951 951

952**get** `/batches`952**get** `/batches`

953 953

954List your organization's batches.954List batches

955 955

956### Query Parameters956### Query Parameters

957 957

1029 1029

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

1031 1031

1032 - `data: optional array of object { code, line, message, param }`1032 - `data: optional array of BatchError`

1033 1033

1034 - `code: optional string`1034 - `code: optional string`

1035 1035

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

1086 offers a wide range of models with different capabilities, performance1086 offers a wide range of models with different capabilities, performance

1087 characteristics, and price points. Refer to the [model1087 characteristics, and price points. Refer to the [model

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

1089 1089

1090 - `output_file_id: optional string`1090 - `output_file_id: optional string`

1091 1091

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

1093 1093

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

1095 1095

1096 The request counts for different statuses within the batch.1096 The request counts for different statuses within the batch.

1097 1097

1124 - `cached_tokens: number`1124 - `cached_tokens: number`

1125 1125

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

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

1128 1128

1129 - `output_tokens: number`1129 - `output_tokens: number`

1130 1130

1341 1341

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

1343 1343

1344 - `data: optional array of object { code, line, message, param }`1344 - `data: optional array of BatchError`

1345 1345

1346 - `code: optional string`1346 - `code: optional string`

1347 1347

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

1398 offers a wide range of models with different capabilities, performance1398 offers a wide range of models with different capabilities, performance

1399 characteristics, and price points. Refer to the [model1399 characteristics, and price points. Refer to the [model

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

1401 1401

1402 - `output_file_id: optional string`1402 - `output_file_id: optional string`

1403 1403

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

1405 1405

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

1407 1407

1408 The request counts for different statuses within the batch.1408 The request counts for different statuses within the batch.

1409 1409

1436 - `cached_tokens: number`1436 - `cached_tokens: number`

1437 1437

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

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

1440 1440

1441 - `output_tokens: number`1441 - `output_tokens: number`

1442 1442

1454 1454

1455 The total number of tokens used.1455 The total number of tokens used.

1456 1456

1457### Batch Error

1458

1459- `BatchError object { code, line, message, param }`

1460

1461 - `code: optional string`

1462

1463 An error code identifying the error type.

1464

1465 - `line: optional number`

1466

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

1468

1469 - `message: optional string`

1470

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

1472

1473 - `param: optional string`

1474

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

1476

1477### Batch Request Counts

1478

1479- `BatchRequestCounts object { completed, failed, total }`

1480

1481 The request counts for different statuses within the batch.

1482

1483 - `completed: number`

1484

1485 Number of requests that have been completed successfully.

1486

1487 - `failed: number`

1488

1489 Number of requests that have failed.

1490

1491 - `total: number`

1492

1493 Total number of requests in the batch.

1494

1457### Batch Usage1495### Batch Usage

1458 1496

1459- `BatchUsage object { input_tokens, input_tokens_details, output_tokens, 2 more }`1497- `BatchUsage object { input_tokens, input_tokens_details, output_tokens, 2 more }`

1473 - `cached_tokens: number`1511 - `cached_tokens: number`

1474 1512

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

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

1477 1515

1478 - `output_tokens: number`1516 - `output_tokens: number`

1479 1517

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

Batches

Create batch

Body Parameters

Returns

Example

Response

Example

Response

Retrieve batch

Path Parameters

Returns

Example

Response

Example

Response

Cancel batch

Path Parameters

Returns

Example

Response

Example

Response

List batches

Query Parameters

Returns

Example

Response

Example

Response

Domain Types

Batch

Batch Error

Batch Request Counts

Batch Usage