Batches

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

Retrieve batch

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

get /batches/{batch_id}

Retrieves a 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<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.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": [
      {
        "code": "code",
        "line": 0,
        "message": "message",
        "param": "param"
      }
    ],
    "object": "object"
  },
  "expired_at": 0,
  "expires_at": 0,
  "failed_at": 0,
  "finalizing_at": 0,
  "in_progress_at": 0,
  "metadata": {
    "foo": "string"
  },
  "model": "model",
  "output_file_id": "output_file_id",
  "request_counts": {
    "completed": 0,
    "failed": 0,
    "total": 0
  },
  "usage": {
    "input_tokens": 0,
    "input_tokens_details": {
      "cached_tokens": 0
    },
    "output_tokens": 0,
    "output_tokens_details": {
      "reasoning_tokens": 0
    },
    "total_tokens": 0
  }
}

Cancel batch

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

post /batches/{batch_id}/cancel

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

Parameters

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<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.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": [
      {
        "code": "code",
        "line": 0,
        "message": "message",
        "param": "param"
      }
    ],
    "object": "object"
  },
  "expired_at": 0,
  "expires_at": 0,
  "failed_at": 0,
  "finalizing_at": 0,
  "in_progress_at": 0,
  "metadata": {
    "foo": "string"
  },
  "model": "model",
  "output_file_id": "output_file_id",
  "request_counts": {
    "completed": 0,
    "failed": 0,
    "total": 0
  },
  "usage": {
    "input_tokens": 0,
    "input_tokens_details": {
      "cached_tokens": 0
    },
    "output_tokens": 0,
    "output_tokens_details": {
      "reasoning_tokens": 0
    },
    "total_tokens": 0
  }
}

List batches

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

get /batches

List your organization's 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<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.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": [
          {
            "code": "code",
            "line": 0,
            "message": "message",
            "param": "param"
          }
        ],
        "object": "object"
      },
      "expired_at": 0,
      "expires_at": 0,
      "failed_at": 0,
      "finalizing_at": 0,
      "in_progress_at": 0,
      "metadata": {
        "foo": "string"
      },
      "model": "model",
      "output_file_id": "output_file_id",
      "request_counts": {
        "completed": 0,
        "failed": 0,
        "total": 0
      },
      "usage": {
        "input_tokens": 0,
        "input_tokens_details": {
          "cached_tokens": 0
        },
        "output_tokens": 0,
        "output_tokens_details": {
          "reasoning_tokens": 0
        },
        "total_tokens": 0
      }
    }
  ],
  "has_more": true,
  "object": "list",
  "first_id": "batch_abc123",
  "last_id": "batch_abc456"
}

Domain Types

Batch

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.

Batch Error

class BatchError:
- 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.

Batch Request Counts

class BatchRequestCounts:

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.

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 +238 −22

6 6

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

8 8

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

10 10

11### Parameters11### Parameters

12 12

135 135

136 - `Optional<Errors> errors`136 - `Optional<Errors> errors`

137 137

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

139

140 - `Optional<String> code`

141

142 An error code identifying the error type.

143

144 - `Optional<Long> line`

145

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

147

148 - `Optional<String> message`

149

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

151

152 - `Optional<String> param`

153

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

139 155

140 - `Optional<String> object_`156 - `Optional<String> object_`

141 157

181 197

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

183 199

184 - `Optional<JsonValue> requestCounts`200 - `Optional<BatchRequestCounts> requestCounts`

201

202 The request counts for different statuses within the batch.

203

204 - `long completed`

205

206 Number of requests that have been completed successfully.

207

208 - `long failed`

209

210 Number of requests that have failed.

211

212 - `long total`

213

214 Total number of requests in the batch.

185 215

186 - `Optional<BatchUsage> usage`216 - `Optional<BatchUsage> usage`

187 217

261 "error_file_id": "error_file_id",291 "error_file_id": "error_file_id",

262 "errors": {292 "errors": {

263 "data": [293 "data": [

264 {}294 {

295 "code": "code",

296 "line": 0,

297 "message": "message",

298 "param": "param"

299 }

265 ],300 ],

266 "object": "object"301 "object": "object"

267 },302 },

275 },310 },

276 "model": "model",311 "model": "model",

277 "output_file_id": "output_file_id",312 "output_file_id": "output_file_id",

278 "request_counts": {},313 "request_counts": {

314 "completed": 0,

315 "failed": 0,

316 "total": 0

317 },

279 "usage": {318 "usage": {

280 "input_tokens": 0,319 "input_tokens": 0,

281 "input_tokens_details": {320 "input_tokens_details": {

296 335

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

298 337

299Retrieve batch338Retrieves a batch.

300 339

301### Parameters340### Parameters

302 341

370 409

371 - `Optional<Errors> errors`410 - `Optional<Errors> errors`

372 411

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

413

414 - `Optional<String> code`

415

416 An error code identifying the error type.

417

418 - `Optional<Long> line`

419

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

421

422 - `Optional<String> message`

423

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

425

426 - `Optional<String> param`

427

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

374 429

375 - `Optional<String> object_`430 - `Optional<String> object_`

376 431

416 471

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

418 473

419 - `Optional<JsonValue> requestCounts`474 - `Optional<BatchRequestCounts> requestCounts`

475

476 The request counts for different statuses within the batch.

477

478 - `long completed`

479

480 Number of requests that have been completed successfully.

481

482 - `long failed`

483

484 Number of requests that have failed.

485

486 - `long total`

487

488 Total number of requests in the batch.

420 489

421 - `Optional<BatchUsage> usage`490 - `Optional<BatchUsage> usage`

422 491

491 "error_file_id": "error_file_id",560 "error_file_id": "error_file_id",

492 "errors": {561 "errors": {

493 "data": [562 "data": [

494 {}563 {

564 "code": "code",

565 "line": 0,

566 "message": "message",

567 "param": "param"

568 }

495 ],569 ],

496 "object": "object"570 "object": "object"

497 },571 },

505 },579 },

506 "model": "model",580 "model": "model",

507 "output_file_id": "output_file_id",581 "output_file_id": "output_file_id",

508 "request_counts": {},582 "request_counts": {

583 "completed": 0,

584 "failed": 0,

585 "total": 0

586 },

509 "usage": {587 "usage": {

510 "input_tokens": 0,588 "input_tokens": 0,

511 "input_tokens_details": {589 "input_tokens_details": {

526 604

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

528 606

529Cancel batch607Cancels 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.

530 608

531### Parameters609### Parameters

532 610

600 678

601 - `Optional<Errors> errors`679 - `Optional<Errors> errors`

602 680

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

682

683 - `Optional<String> code`

684

685 An error code identifying the error type.

686

687 - `Optional<Long> line`

688

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

690

691 - `Optional<String> message`

692

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

694

695 - `Optional<String> param`

696

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

604 698

605 - `Optional<String> object_`699 - `Optional<String> object_`

606 700

646 740

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

648 742

649 - `Optional<JsonValue> requestCounts`743 - `Optional<BatchRequestCounts> requestCounts`

744

745 The request counts for different statuses within the batch.

746

747 - `long completed`

748

749 Number of requests that have been completed successfully.

750

751 - `long failed`

752

753 Number of requests that have failed.

754

755 - `long total`

756

757 Total number of requests in the batch.

650 758

651 - `Optional<BatchUsage> usage`759 - `Optional<BatchUsage> usage`

652 760

721 "error_file_id": "error_file_id",829 "error_file_id": "error_file_id",

722 "errors": {830 "errors": {

723 "data": [831 "data": [

724 {}832 {

833 "code": "code",

834 "line": 0,

835 "message": "message",

836 "param": "param"

837 }

725 ],838 ],

726 "object": "object"839 "object": "object"

727 },840 },

735 },848 },

736 "model": "model",849 "model": "model",

737 "output_file_id": "output_file_id",850 "output_file_id": "output_file_id",

738 "request_counts": {},851 "request_counts": {

852 "completed": 0,

853 "failed": 0,

854 "total": 0

855 },

739 "usage": {856 "usage": {

740 "input_tokens": 0,857 "input_tokens": 0,

741 "input_tokens_details": {858 "input_tokens_details": {

756 873

757**get** `/batches`874**get** `/batches`

758 875

759List batches876List your organization's batches.

760 877

761### Parameters878### Parameters

762 879

836 953

837 - `Optional<Errors> errors`954 - `Optional<Errors> errors`

838 955

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

957

958 - `Optional<String> code`

959

960 An error code identifying the error type.

961

962 - `Optional<Long> line`

963

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

965

966 - `Optional<String> message`

967

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

969

970 - `Optional<String> param`

971

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

840 973

841 - `Optional<String> object_`974 - `Optional<String> object_`

842 975

882 1015

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

884 1017

885 - `Optional<JsonValue> requestCounts`1018 - `Optional<BatchRequestCounts> requestCounts`

1019

1020 The request counts for different statuses within the batch.

1021

1022 - `long completed`

1023

1024 Number of requests that have been completed successfully.

1025

1026 - `long failed`

1027

1028 Number of requests that have failed.

1029

1030 - `long total`

1031

1032 Total number of requests in the batch.

886 1033

887 - `Optional<BatchUsage> usage`1034 - `Optional<BatchUsage> usage`

888 1035

959 "error_file_id": "error_file_id",1106 "error_file_id": "error_file_id",

960 "errors": {1107 "errors": {

961 "data": [1108 "data": [

962 {}1109 {

1110 "code": "code",

1111 "line": 0,

1112 "message": "message",

1113 "param": "param"

1114 }

963 ],1115 ],

964 "object": "object"1116 "object": "object"

965 },1117 },

973 },1125 },

974 "model": "model",1126 "model": "model",

975 "output_file_id": "output_file_id",1127 "output_file_id": "output_file_id",

976 "request_counts": {},1128 "request_counts": {

1129 "completed": 0,

1130 "failed": 0,

1131 "total": 0

1132 },

977 "usage": {1133 "usage": {

978 "input_tokens": 0,1134 "input_tokens": 0,

979 "input_tokens_details": {1135 "input_tokens_details": {

1062 1218

1063 - `Optional<Errors> errors`1219 - `Optional<Errors> errors`

1064 1220

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

1222

1223 - `Optional<String> code`

1224

1225 An error code identifying the error type.

1226

1227 - `Optional<Long> line`

1228

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

1230

1231 - `Optional<String> message`

1232

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

1234

1235 - `Optional<String> param`

1236

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

1066 1238

1067 - `Optional<String> object_`1239 - `Optional<String> object_`

1068 1240

1108 1280

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

1110 1282

1111 - `Optional<JsonValue> requestCounts`1283 - `Optional<BatchRequestCounts> requestCounts`

1284

1285 The request counts for different statuses within the batch.

1286

1287 - `long completed`

1288

1289 Number of requests that have been completed successfully.

1290

1291 - `long failed`

1292

1293 Number of requests that have failed.

1294

1295 - `long total`

1296

1297 Total number of requests in the batch.

1112 1298

1113 - `Optional<BatchUsage> usage`1299 - `Optional<BatchUsage> usage`

1114 1300

1149 1335

1150- `class BatchError:`1336- `class BatchError:`

1151 1337

1338 - `Optional<String> code`

1339

1340 An error code identifying the error type.

1341

1342 - `Optional<Long> line`

1343

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

1345

1346 - `Optional<String> message`

1347

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

1349

1350 - `Optional<String> param`

1351

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

1353

1152### Batch Request Counts1354### Batch Request Counts

1153 1355

1154- `class BatchRequestCounts:`1356- `class BatchRequestCounts:`

1155 1357

1358 The request counts for different statuses within the batch.

1359

1360 - `long completed`

1361

1362 Number of requests that have been completed successfully.

1363

1364 - `long failed`

1365

1366 Number of requests that have failed.

1367

1368 - `long total`

1369

1370 Total number of requests in the batch.

1371

1156### Batch Usage1372### Batch Usage

1157 1373

1158- `class BatchUsage:`1374- `class BatchUsage:`

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