Batches

Create batch

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

post /batches

Create batch

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<JsonValue>> data
  - 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<JsonValue> requestCounts
- 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": [
      {}
    ],
    "object": "object"
  },
  "expired_at": 0,
  "expires_at": 0,
  "failed_at": 0,
  "finalizing_at": 0,
  "in_progress_at": 0,
  "metadata": {
    "foo": "string"
  },
  "model": "model",
  "output_file_id": "output_file_id",
  "request_counts": {},
  "usage": {
    "input_tokens": 0,
    "input_tokens_details": {
      "cached_tokens": 0
    },
    "output_tokens": 0,
    "output_tokens_details": {
      "reasoning_tokens": 0
    },
    "total_tokens": 0
  }
}

Retrieve batch

Batch batches().retrieve(BatchRetrieveParamsparams = BatchRetrieveParams.none(), RequestOptionsrequestOptions = RequestOptions.none())

get /batches/{batch_id}

Retrieve batch

Parameters

BatchRetrieveParams params
- Optional<String> batchId

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<JsonValue>> data
  - 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<JsonValue> requestCounts
- 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.BatchRetrieveParams;

public final class Main {
    private Main() {}

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

        Batch batch = client.batches().retrieve("batch_id");
    }
}

Response

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

Cancel batch

Batch batches().cancel(BatchCancelParamsparams = BatchCancelParams.none(), RequestOptionsrequestOptions = RequestOptions.none())

post /batches/{batch_id}/cancel

Cancel batch

Parameters

BatchCancelParams params
- Optional<String> batchId

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<JsonValue>> data
  - 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<JsonValue> requestCounts
- 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.BatchCancelParams;

public final class Main {
    private Main() {}

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

        Batch batch = client.batches().cancel("batch_id");
    }
}

Response

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

List batches

BatchListPage batches().list(BatchListParamsparams = BatchListParams.none(), RequestOptionsrequestOptions = RequestOptions.none())

get /batches

List batches

Parameters

BatchListParams params
- Optional<String> after
  
  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.
- Optional<Long> limit
  
  A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20.

Returns

class Batch:
- 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<JsonValue>> data
  - 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<JsonValue> requestCounts
- 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.BatchListPage;
import com.openai.models.batches.BatchListParams;

public final class Main {
    private Main() {}

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

        BatchListPage page = client.batches().list();
    }
}

Response

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

Domain Types

Batch

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<JsonValue>> data
  - 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<JsonValue> requestCounts
- 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.

Batch Error

class BatchError:

Batch Request Counts

class BatchRequestCounts:

Batch Usage

class BatchUsage:

Represents token usage details including input tokens, output tokens, a breakdown of output tokens, and the total tokens used. Only populated on batches created after September 7, 2025.
- 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.

java/resources/batches/index.md +1191 −0 created

1# Batches

3## Create batch

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

7**post** `/batches`

9Create batch

11### Parameters

13- `BatchCreateParams params`

15 - `CompletionWindow completionWindow`

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

19 - `_24H("24h")`

21 - `Endpoint endpoint`

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

25 - `V1_RESPONSES("/v1/responses")`

27 - `V1_CHAT_COMPLETIONS("/v1/chat/completions")`

29 - `V1_EMBEDDINGS("/v1/embeddings")`

31 - `V1_COMPLETIONS("/v1/completions")`

33 - `V1_MODERATIONS("/v1/moderations")`

35 - `V1_IMAGES_GENERATIONS("/v1/images/generations")`

37 - `V1_IMAGES_EDITS("/v1/images/edits")`

39 - `V1_VIDEOS("/v1/videos")`

41 - `String inputFileId`

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

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

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

49 - `Optional<Metadata> metadata`

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

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

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

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

56 with a maximum length of 512 characters.

58 - `Optional<OutputExpiresAfter> outputExpiresAfter`

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

62 - `JsonValue; anchor "created_at"constant`

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

66 - `CREATED_AT("created_at")`

68 - `long seconds`

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

72### Returns

74- `class Batch:`

76 - `String id`

78 - `String completionWindow`

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

82 - `long createdAt`

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

86 - `String endpoint`

88 The OpenAI API endpoint used by the batch.

90 - `String inputFileId`

92 The ID of the input file for the batch.

94 - `JsonValue; object_ "batch"constant`

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

98 - `BATCH("batch")`

100 - `Status status`

101

102 The current status of the batch.

103

104 - `VALIDATING("validating")`

105

106 - `FAILED("failed")`

107

108 - `IN_PROGRESS("in_progress")`

109

110 - `FINALIZING("finalizing")`

111

112 - `COMPLETED("completed")`

113

114 - `EXPIRED("expired")`

115

116 - `CANCELLING("cancelling")`

117

118 - `CANCELLED("cancelled")`

119

120 - `Optional<Long> cancelledAt`

121

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

123

124 - `Optional<Long> cancellingAt`

125

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

127

128 - `Optional<Long> completedAt`

129

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

131

132 - `Optional<String> errorFileId`

133

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

135

136 - `Optional<Errors> errors`

137

138 - `Optional<List<JsonValue>> data`

139

140 - `Optional<String> object_`

141

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

143

144 - `Optional<Long> expiredAt`

145

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

147

148 - `Optional<Long> expiresAt`

149

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

151

152 - `Optional<Long> failedAt`

153

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

155

156 - `Optional<Long> finalizingAt`

157

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

159

160 - `Optional<Long> inProgressAt`

161

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

163

164 - `Optional<Metadata> metadata`

165

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

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

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

169

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

171 with a maximum length of 512 characters.

172

173 - `Optional<String> model`

174

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

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

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

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

179

180 - `Optional<String> outputFileId`

181

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

183

184 - `Optional<JsonValue> requestCounts`

185

186 - `Optional<BatchUsage> usage`

187

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

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

190 batches created after September 7, 2025.

191

192 - `long inputTokens`

193

194 The number of input tokens.

195

196 - `InputTokensDetails inputTokensDetails`

197

198 A detailed breakdown of the input tokens.

199

200 - `long cachedTokens`

201

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

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

204

205 - `long outputTokens`

206

207 The number of output tokens.

208

209 - `OutputTokensDetails outputTokensDetails`

210

211 A detailed breakdown of the output tokens.

212

213 - `long reasoningTokens`

214

215 The number of reasoning tokens.

216

217 - `long totalTokens`

218

219 The total number of tokens used.

220

221### Example

222

223```java

224package com.openai.example;

225

226import com.openai.client.OpenAIClient;

227import com.openai.client.okhttp.OpenAIOkHttpClient;

228import com.openai.models.batches.Batch;

229import com.openai.models.batches.BatchCreateParams;

230

231public final class Main {

232 private Main() {}

233

234 public static void main(String[] args) {

235 OpenAIClient client = OpenAIOkHttpClient.fromEnv();

236

237 BatchCreateParams params = BatchCreateParams.builder()

238 .completionWindow(BatchCreateParams.CompletionWindow._24H)

239 .endpoint(BatchCreateParams.Endpoint.V1_RESPONSES)

240 .inputFileId("input_file_id")

241 .build();

242 Batch batch = client.batches().create(params);

243 }

244}

245```

246

247#### Response

248

249```json

250{

251 "id": "id",

252 "completion_window": "completion_window",

253 "created_at": 0,

254 "endpoint": "endpoint",

255 "input_file_id": "input_file_id",

256 "object": "batch",

257 "status": "validating",

258 "cancelled_at": 0,

259 "cancelling_at": 0,

260 "completed_at": 0,

261 "error_file_id": "error_file_id",

262 "errors": {

263 "data": [

264 {}

265 ],

266 "object": "object"

267 },

268 "expired_at": 0,

269 "expires_at": 0,

270 "failed_at": 0,

271 "finalizing_at": 0,

272 "in_progress_at": 0,

273 "metadata": {

274 "foo": "string"

275 },

276 "model": "model",

277 "output_file_id": "output_file_id",

278 "request_counts": {},

279 "usage": {

280 "input_tokens": 0,

281 "input_tokens_details": {

282 "cached_tokens": 0

283 },

284 "output_tokens": 0,

285 "output_tokens_details": {

286 "reasoning_tokens": 0

287 },

288 "total_tokens": 0

289 }

290}

291```

292

293## Retrieve batch

294

295`Batch batches().retrieve(BatchRetrieveParamsparams = BatchRetrieveParams.none(), RequestOptionsrequestOptions = RequestOptions.none())`

296

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

298

299Retrieve batch

300

301### Parameters

302

303- `BatchRetrieveParams params`

304

305 - `Optional<String> batchId`

306

307### Returns

308

309- `class Batch:`

310

311 - `String id`

312

313 - `String completionWindow`

314

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

316

317 - `long createdAt`

318

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

320

321 - `String endpoint`

322

323 The OpenAI API endpoint used by the batch.

324

325 - `String inputFileId`

326

327 The ID of the input file for the batch.

328

329 - `JsonValue; object_ "batch"constant`

330

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

332

333 - `BATCH("batch")`

334

335 - `Status status`

336

337 The current status of the batch.

338

339 - `VALIDATING("validating")`

340

341 - `FAILED("failed")`

342

343 - `IN_PROGRESS("in_progress")`

344

345 - `FINALIZING("finalizing")`

346

347 - `COMPLETED("completed")`

348

349 - `EXPIRED("expired")`

350

351 - `CANCELLING("cancelling")`

352

353 - `CANCELLED("cancelled")`

354

355 - `Optional<Long> cancelledAt`

356

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

358

359 - `Optional<Long> cancellingAt`

360

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

362

363 - `Optional<Long> completedAt`

364

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

366

367 - `Optional<String> errorFileId`

368

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

370

371 - `Optional<Errors> errors`

372

373 - `Optional<List<JsonValue>> data`

374

375 - `Optional<String> object_`

376

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

378

379 - `Optional<Long> expiredAt`

380

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

382

383 - `Optional<Long> expiresAt`

384

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

386

387 - `Optional<Long> failedAt`

388

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

390

391 - `Optional<Long> finalizingAt`

392

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

394

395 - `Optional<Long> inProgressAt`

396

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

398

399 - `Optional<Metadata> metadata`

400

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

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

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

404

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

406 with a maximum length of 512 characters.

407

408 - `Optional<String> model`

409

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

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

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

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

414

415 - `Optional<String> outputFileId`

416

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

418

419 - `Optional<JsonValue> requestCounts`

420

421 - `Optional<BatchUsage> usage`

422

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

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

425 batches created after September 7, 2025.

426

427 - `long inputTokens`

428

429 The number of input tokens.

430

431 - `InputTokensDetails inputTokensDetails`

432

433 A detailed breakdown of the input tokens.

434

435 - `long cachedTokens`

436

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

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

439

440 - `long outputTokens`

441

442 The number of output tokens.

443

444 - `OutputTokensDetails outputTokensDetails`

445

446 A detailed breakdown of the output tokens.

447

448 - `long reasoningTokens`

449

450 The number of reasoning tokens.

451

452 - `long totalTokens`

453

454 The total number of tokens used.

455

456### Example

457

458```java

459package com.openai.example;

460

461import com.openai.client.OpenAIClient;

462import com.openai.client.okhttp.OpenAIOkHttpClient;

463import com.openai.models.batches.Batch;

464import com.openai.models.batches.BatchRetrieveParams;

465

466public final class Main {

467 private Main() {}

468

469 public static void main(String[] args) {

470 OpenAIClient client = OpenAIOkHttpClient.fromEnv();

471

472 Batch batch = client.batches().retrieve("batch_id");

473 }

474}

475```

476

477#### Response

478

479```json

480{

481 "id": "id",

482 "completion_window": "completion_window",

483 "created_at": 0,

484 "endpoint": "endpoint",

485 "input_file_id": "input_file_id",

486 "object": "batch",

487 "status": "validating",

488 "cancelled_at": 0,

489 "cancelling_at": 0,

490 "completed_at": 0,

491 "error_file_id": "error_file_id",

492 "errors": {

493 "data": [

494 {}

495 ],

496 "object": "object"

497 },

498 "expired_at": 0,

499 "expires_at": 0,

500 "failed_at": 0,

501 "finalizing_at": 0,

502 "in_progress_at": 0,

503 "metadata": {

504 "foo": "string"

505 },

506 "model": "model",

507 "output_file_id": "output_file_id",

508 "request_counts": {},

509 "usage": {

510 "input_tokens": 0,

511 "input_tokens_details": {

512 "cached_tokens": 0

513 },

514 "output_tokens": 0,

515 "output_tokens_details": {

516 "reasoning_tokens": 0

517 },

518 "total_tokens": 0

519 }

520}

521```

522

523## Cancel batch

524

525`Batch batches().cancel(BatchCancelParamsparams = BatchCancelParams.none(), RequestOptionsrequestOptions = RequestOptions.none())`

526

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

528

529Cancel batch

530

531### Parameters

532

533- `BatchCancelParams params`

534

535 - `Optional<String> batchId`

536

537### Returns

538

539- `class Batch:`

540

541 - `String id`

542

543 - `String completionWindow`

544

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

546

547 - `long createdAt`

548

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

550

551 - `String endpoint`

552

553 The OpenAI API endpoint used by the batch.

554

555 - `String inputFileId`

556

557 The ID of the input file for the batch.

558

559 - `JsonValue; object_ "batch"constant`

560

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

562

563 - `BATCH("batch")`

564

565 - `Status status`

566

567 The current status of the batch.

568

569 - `VALIDATING("validating")`

570

571 - `FAILED("failed")`

572

573 - `IN_PROGRESS("in_progress")`

574

575 - `FINALIZING("finalizing")`

576

577 - `COMPLETED("completed")`

578

579 - `EXPIRED("expired")`

580

581 - `CANCELLING("cancelling")`

582

583 - `CANCELLED("cancelled")`

584

585 - `Optional<Long> cancelledAt`

586

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

588

589 - `Optional<Long> cancellingAt`

590

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

592

593 - `Optional<Long> completedAt`

594

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

596

597 - `Optional<String> errorFileId`

598

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

600

601 - `Optional<Errors> errors`

602

603 - `Optional<List<JsonValue>> data`

604

605 - `Optional<String> object_`

606

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

608

609 - `Optional<Long> expiredAt`

610

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

612

613 - `Optional<Long> expiresAt`

614

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

616

617 - `Optional<Long> failedAt`

618

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

620

621 - `Optional<Long> finalizingAt`

622

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

624

625 - `Optional<Long> inProgressAt`

626

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

628

629 - `Optional<Metadata> metadata`

630

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

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

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

634

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

636 with a maximum length of 512 characters.

637

638 - `Optional<String> model`

639

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

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

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

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

644

645 - `Optional<String> outputFileId`

646

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

648

649 - `Optional<JsonValue> requestCounts`

650

651 - `Optional<BatchUsage> usage`

652

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

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

655 batches created after September 7, 2025.

656

657 - `long inputTokens`

658

659 The number of input tokens.

660

661 - `InputTokensDetails inputTokensDetails`

662

663 A detailed breakdown of the input tokens.

664

665 - `long cachedTokens`

666

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

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

669

670 - `long outputTokens`

671

672 The number of output tokens.

673

674 - `OutputTokensDetails outputTokensDetails`

675

676 A detailed breakdown of the output tokens.

677

678 - `long reasoningTokens`

679

680 The number of reasoning tokens.

681

682 - `long totalTokens`

683

684 The total number of tokens used.

685

686### Example

687

688```java

689package com.openai.example;

690

691import com.openai.client.OpenAIClient;

692import com.openai.client.okhttp.OpenAIOkHttpClient;

693import com.openai.models.batches.Batch;

694import com.openai.models.batches.BatchCancelParams;

695

696public final class Main {

697 private Main() {}

698

699 public static void main(String[] args) {

700 OpenAIClient client = OpenAIOkHttpClient.fromEnv();

701

702 Batch batch = client.batches().cancel("batch_id");

703 }

704}

705```

706

707#### Response

708

709```json

710{

711 "id": "id",

712 "completion_window": "completion_window",

713 "created_at": 0,

714 "endpoint": "endpoint",

715 "input_file_id": "input_file_id",

716 "object": "batch",

717 "status": "validating",

718 "cancelled_at": 0,

719 "cancelling_at": 0,

720 "completed_at": 0,

721 "error_file_id": "error_file_id",

722 "errors": {

723 "data": [

724 {}

725 ],

726 "object": "object"

727 },

728 "expired_at": 0,

729 "expires_at": 0,

730 "failed_at": 0,

731 "finalizing_at": 0,

732 "in_progress_at": 0,

733 "metadata": {

734 "foo": "string"

735 },

736 "model": "model",

737 "output_file_id": "output_file_id",

738 "request_counts": {},

739 "usage": {

740 "input_tokens": 0,

741 "input_tokens_details": {

742 "cached_tokens": 0

743 },

744 "output_tokens": 0,

745 "output_tokens_details": {

746 "reasoning_tokens": 0

747 },

748 "total_tokens": 0

749 }

750}

751```

752

753## List batches

754

755`BatchListPage batches().list(BatchListParamsparams = BatchListParams.none(), RequestOptionsrequestOptions = RequestOptions.none())`

756

757**get** `/batches`

758

759List batches

760

761### Parameters

762

763- `BatchListParams params`

764

765 - `Optional<String> after`

766

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

768

769 - `Optional<Long> limit`

770

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

772

773### Returns

774

775- `class Batch:`

776

777 - `String id`

778

779 - `String completionWindow`

780

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

782

783 - `long createdAt`

784

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

786

787 - `String endpoint`

788

789 The OpenAI API endpoint used by the batch.

790

791 - `String inputFileId`

792

793 The ID of the input file for the batch.

794

795 - `JsonValue; object_ "batch"constant`

796

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

798

799 - `BATCH("batch")`

800

801 - `Status status`

802

803 The current status of the batch.

804

805 - `VALIDATING("validating")`

806

807 - `FAILED("failed")`

808

809 - `IN_PROGRESS("in_progress")`

810

811 - `FINALIZING("finalizing")`

812

813 - `COMPLETED("completed")`

814

815 - `EXPIRED("expired")`

816

817 - `CANCELLING("cancelling")`

818

819 - `CANCELLED("cancelled")`

820

821 - `Optional<Long> cancelledAt`

822

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

824

825 - `Optional<Long> cancellingAt`

826

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

828

829 - `Optional<Long> completedAt`

830

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

832

833 - `Optional<String> errorFileId`

834

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

836

837 - `Optional<Errors> errors`

838

839 - `Optional<List<JsonValue>> data`

840

841 - `Optional<String> object_`

842

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

844

845 - `Optional<Long> expiredAt`

846

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

848

849 - `Optional<Long> expiresAt`

850

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

852

853 - `Optional<Long> failedAt`

854

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

856

857 - `Optional<Long> finalizingAt`

858

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

860

861 - `Optional<Long> inProgressAt`

862

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

864

865 - `Optional<Metadata> metadata`

866

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

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

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

870

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

872 with a maximum length of 512 characters.

873

874 - `Optional<String> model`

875

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

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

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

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

880

881 - `Optional<String> outputFileId`

882

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

884

885 - `Optional<JsonValue> requestCounts`

886

887 - `Optional<BatchUsage> usage`

888

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

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

891 batches created after September 7, 2025.

892

893 - `long inputTokens`

894

895 The number of input tokens.

896

897 - `InputTokensDetails inputTokensDetails`

898

899 A detailed breakdown of the input tokens.

900

901 - `long cachedTokens`

902

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

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

905

906 - `long outputTokens`

907

908 The number of output tokens.

909

910 - `OutputTokensDetails outputTokensDetails`

911

912 A detailed breakdown of the output tokens.

913

914 - `long reasoningTokens`

915

916 The number of reasoning tokens.

917

918 - `long totalTokens`

919

920 The total number of tokens used.

921

922### Example

923

924```java

925package com.openai.example;

926

927import com.openai.client.OpenAIClient;

928import com.openai.client.okhttp.OpenAIOkHttpClient;

929import com.openai.models.batches.BatchListPage;

930import com.openai.models.batches.BatchListParams;

931

932public final class Main {

933 private Main() {}

934

935 public static void main(String[] args) {

936 OpenAIClient client = OpenAIOkHttpClient.fromEnv();

937

938 BatchListPage page = client.batches().list();

939 }

940}

941```

942

943#### Response

944

945```json

946{

947 "data": [

948 {

949 "id": "id",

950 "completion_window": "completion_window",

951 "created_at": 0,

952 "endpoint": "endpoint",

953 "input_file_id": "input_file_id",

954 "object": "batch",

955 "status": "validating",

956 "cancelled_at": 0,

957 "cancelling_at": 0,

958 "completed_at": 0,

959 "error_file_id": "error_file_id",

960 "errors": {

961 "data": [

962 {}

963 ],

964 "object": "object"

965 },

966 "expired_at": 0,

967 "expires_at": 0,

968 "failed_at": 0,

969 "finalizing_at": 0,

970 "in_progress_at": 0,

971 "metadata": {

972 "foo": "string"

973 },

974 "model": "model",

975 "output_file_id": "output_file_id",

976 "request_counts": {},

977 "usage": {

978 "input_tokens": 0,

979 "input_tokens_details": {

980 "cached_tokens": 0

981 },

982 "output_tokens": 0,

983 "output_tokens_details": {

984 "reasoning_tokens": 0

985 },

986 "total_tokens": 0

987 }

988 }

989 ],

990 "has_more": true,

991 "object": "list",

992 "first_id": "batch_abc123",

993 "last_id": "batch_abc456"

994}

995```

996

997## Domain Types

998

999### Batch

1000

1001- `class Batch:`

1002

1003 - `String id`

1004

1005 - `String completionWindow`

1006

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

1008

1009 - `long createdAt`

1010

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

1012

1013 - `String endpoint`

1014

1015 The OpenAI API endpoint used by the batch.

1016

1017 - `String inputFileId`

1018

1019 The ID of the input file for the batch.

1020

1021 - `JsonValue; object_ "batch"constant`

1022

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

1024

1025 - `BATCH("batch")`

1026

1027 - `Status status`

1028

1029 The current status of the batch.

1030

1031 - `VALIDATING("validating")`

1032

1033 - `FAILED("failed")`

1034

1035 - `IN_PROGRESS("in_progress")`

1036

1037 - `FINALIZING("finalizing")`

1038

1039 - `COMPLETED("completed")`

1040

1041 - `EXPIRED("expired")`

1042

1043 - `CANCELLING("cancelling")`

1044

1045 - `CANCELLED("cancelled")`

1046

1047 - `Optional<Long> cancelledAt`

1048

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

1050

1051 - `Optional<Long> cancellingAt`

1052

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

1054

1055 - `Optional<Long> completedAt`

1056

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

1058

1059 - `Optional<String> errorFileId`

1060

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

1062

1063 - `Optional<Errors> errors`

1064

1065 - `Optional<List<JsonValue>> data`

1066

1067 - `Optional<String> object_`

1068

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

1070

1071 - `Optional<Long> expiredAt`

1072

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

1074

1075 - `Optional<Long> expiresAt`

1076

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

1078

1079 - `Optional<Long> failedAt`

1080

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

1082

1083 - `Optional<Long> finalizingAt`

1084

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

1086

1087 - `Optional<Long> inProgressAt`

1088

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

1090

1091 - `Optional<Metadata> metadata`

1092

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

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

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

1096

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

1098 with a maximum length of 512 characters.

1099

1100 - `Optional<String> model`

1101

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

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

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

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

1106

1107 - `Optional<String> outputFileId`

1108

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

1110

1111 - `Optional<JsonValue> requestCounts`

1112

1113 - `Optional<BatchUsage> usage`

1114

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

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

1117 batches created after September 7, 2025.

1118

1119 - `long inputTokens`

1120

1121 The number of input tokens.

1122

1123 - `InputTokensDetails inputTokensDetails`

1124

1125 A detailed breakdown of the input tokens.

1126

1127 - `long cachedTokens`

1128

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

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

1131

1132 - `long outputTokens`

1133

1134 The number of output tokens.

1135

1136 - `OutputTokensDetails outputTokensDetails`

1137

1138 A detailed breakdown of the output tokens.

1139

1140 - `long reasoningTokens`

1141

1142 The number of reasoning tokens.

1143

1144 - `long totalTokens`

1145

1146 The total number of tokens used.

1147

1148### Batch Error

1149

1150- `class BatchError:`

1151

1152### Batch Request Counts

1153

1154- `class BatchRequestCounts:`

1155

1156### Batch Usage

1157

1158- `class BatchUsage:`

1159

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

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

1162 batches created after September 7, 2025.

1163

1164 - `long inputTokens`

1165

1166 The number of input tokens.

1167

1168 - `InputTokensDetails inputTokensDetails`

1169

1170 A detailed breakdown of the input tokens.

1171

1172 - `long cachedTokens`

1173

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

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

1176

1177 - `long outputTokens`

1178

1179 The number of output tokens.

1180

1181 - `OutputTokensDetails outputTokensDetails`

1182

1183 A detailed breakdown of the output tokens.

1184

1185 - `long reasoningTokens`

1186

1187 The number of reasoning tokens.

1188

1189 - `long totalTokens`

1190

1191 The total number of tokens used.

java/resources/batches/index.md 2026-07-07 08:02 UTC to 2026-07-09 20:58 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