java/resources/batches/methods/create/index.md

Create batch

Batch batches().create(BatchCreateParamsparams, RequestOptionsrequestOptions = RequestOptions.none())

post /batches

Creates and executes a batch from an uploaded file of requests

Parameters

BatchCreateParams params
- CompletionWindow completionWindow
  
  The time frame within which the batch should be processed. Currently only 24h is supported.
  - _24H("24h")
- Endpoint endpoint
  
  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/responses")
  - V1_CHAT_COMPLETIONS("/v1/chat/completions")
  - V1_EMBEDDINGS("/v1/embeddings")
  - V1_COMPLETIONS("/v1/completions")
  - V1_MODERATIONS("/v1/moderations")
  - V1_IMAGES_GENERATIONS("/v1/images/generations")
  - V1_IMAGES_EDITS("/v1/images/edits")
  - V1_VIDEOS("/v1/videos")
- String inputFileId
  
  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.
- Optional<Metadata> 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.
- Optional<OutputExpiresAfter> outputExpiresAfter
  
  The expiration policy for the output and/or error file that are generated for a batch.
  - JsonValue; anchor "created_at"constant
    
    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("created_at")
  - long seconds
    
    The number of seconds after the anchor time that the file will expire. Must be between 3600 (1 hour) and 2592000 (30 days).

Returns

class Batch:
- String id
- String completionWindow
  
  The time frame within which the batch should be processed.
- long createdAt
  
  The Unix timestamp (in seconds) for when the batch was created.
- String endpoint
  
  The OpenAI API endpoint used by the batch.
- String inputFileId
  
  The ID of the input file for the batch.
- JsonValue; object_ "batch"constant
  
  The object type, which is always batch.
  - BATCH("batch")
- Status status
  
  The current status of the batch.
  - VALIDATING("validating")
  - FAILED("failed")
  - IN_PROGRESS("in_progress")
  - FINALIZING("finalizing")
  - COMPLETED("completed")
  - EXPIRED("expired")
  - CANCELLING("cancelling")
  - CANCELLED("cancelled")
- Optional<Long> cancelledAt
  
  The Unix timestamp (in seconds) for when the batch was cancelled.
- Optional<Long> cancellingAt
  
  The Unix timestamp (in seconds) for when the batch started cancelling.
- Optional<Long> completedAt
  
  The Unix timestamp (in seconds) for when the batch was completed.
- Optional<String> errorFileId
  
  The ID of the file containing the outputs of requests with errors.
- Optional<Errors> errors
  - Optional<List<BatchError>> data
    - Optional<String> code
      
      An error code identifying the error type.
    - Optional<Long> line
      
      The line number of the input file where the error occurred, if applicable.
    - Optional<String> message
      
      A human-readable message providing more details about the error.
    - Optional<String> param
      
      The name of the parameter that caused the error, if applicable.
  - Optional<String> object_
    
    The object type, which is always list.
- Optional<Long> expiredAt
  
  The Unix timestamp (in seconds) for when the batch expired.
- Optional<Long> expiresAt
  
  The Unix timestamp (in seconds) for when the batch will expire.
- Optional<Long> failedAt
  
  The Unix timestamp (in seconds) for when the batch failed.
- Optional<Long> finalizingAt
  
  The Unix timestamp (in seconds) for when the batch started finalizing.
- Optional<Long> inProgressAt
  
  The Unix timestamp (in seconds) for when the batch started processing.
- Optional<Metadata> 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.
- Optional<String> model
  
  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.
- Optional<String> outputFileId
  
  The ID of the file containing the outputs of successfully executed requests.
- Optional<BatchRequestCounts> requestCounts
  
  The request counts for different statuses within the batch.
  - long completed
    
    Number of requests that have been completed successfully.
  - long failed
    
    Number of requests that have failed.
  - long total
    
    Total number of requests in the batch.
- Optional<BatchUsage> usage
  
  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.
  - long inputTokens
    
    The number of input tokens.
  - InputTokensDetails inputTokensDetails
    
    A detailed breakdown of the input tokens.
    - long cachedTokens
      
      The number of tokens that were retrieved from the cache. More on prompt caching.
  - long outputTokens
    
    The number of output tokens.
  - OutputTokensDetails outputTokensDetails
    
    A detailed breakdown of the output tokens.
    - long reasoningTokens
      
      The number of reasoning tokens.
  - long totalTokens
    
    The total number of tokens used.

Example

package com.openai.example;

import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.batches.Batch;
import com.openai.models.batches.BatchCreateParams;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        OpenAIClient client = OpenAIOkHttpClient.fromEnv();

        BatchCreateParams params = BatchCreateParams.builder()
            .completionWindow(BatchCreateParams.CompletionWindow._24H)
            .endpoint(BatchCreateParams.Endpoint.V1_RESPONSES)
            .inputFileId("input_file_id")
            .build();
        Batch batch = client.batches().create(params);
    }
}

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

java/resources/batches/methods/create/index.md +44 −5

4 4

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

6 6

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

8 8

9### Parameters9### Parameters

10 10

133 133

134 - `Optional<Errors> errors`134 - `Optional<Errors> errors`

135 135

136 - `Optional<List<JsonValue>> data`136 - `Optional<List<BatchError>> data`

137

138 - `Optional<String> code`

139

140 An error code identifying the error type.

141

142 - `Optional<Long> line`

143

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

145

146 - `Optional<String> message`

147

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

149

150 - `Optional<String> param`

151

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

137 153

138 - `Optional<String> object_`154 - `Optional<String> object_`

139 155

179 195

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

181 197

182 - `Optional<JsonValue> requestCounts`198 - `Optional<BatchRequestCounts> requestCounts`

199

200 The request counts for different statuses within the batch.

201

202 - `long completed`

203

204 Number of requests that have been completed successfully.

205

206 - `long failed`

207

208 Number of requests that have failed.

209

210 - `long total`

211

212 Total number of requests in the batch.

183 213

184 - `Optional<BatchUsage> usage`214 - `Optional<BatchUsage> usage`

185 215

259 "error_file_id": "error_file_id",289 "error_file_id": "error_file_id",

260 "errors": {290 "errors": {

261 "data": [291 "data": [

262 {}292 {

293 "code": "code",

294 "line": 0,

295 "message": "message",

296 "param": "param"

297 }

263 ],298 ],

264 "object": "object"299 "object": "object"

265 },300 },

273 },308 },

274 "model": "model",309 "model": "model",

275 "output_file_id": "output_file_id",310 "output_file_id": "output_file_id",

276 "request_counts": {},311 "request_counts": {

312 "completed": 0,

313 "failed": 0,

314 "total": 0

315 },

277 "usage": {316 "usage": {

278 "input_tokens": 0,317 "input_tokens": 0,

279 "input_tokens_details": {318 "input_tokens_details": {