Batches

Create batch

client.Batches.New(ctx, body) (*Batch, error)

post /batches

Creates and executes a batch from an uploaded file of requests

Parameters

body BatchNewParams
- CompletionWindow param.Field[BatchNewParamsCompletionWindow]
  
  The time frame within which the batch should be processed. Currently only 24h is supported.
  - const BatchNewParamsCompletionWindow24h BatchNewParamsCompletionWindow = "24h"
- Endpoint param.Field[BatchNewParamsEndpoint]
  
  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.
  - const BatchNewParamsEndpointV1Responses BatchNewParamsEndpoint = "/v1/responses"
  - const BatchNewParamsEndpointV1ChatCompletions BatchNewParamsEndpoint = "/v1/chat/completions"
  - const BatchNewParamsEndpointV1Embeddings BatchNewParamsEndpoint = "/v1/embeddings"
  - const BatchNewParamsEndpointV1Completions BatchNewParamsEndpoint = "/v1/completions"
  - const BatchNewParamsEndpointV1Moderations BatchNewParamsEndpoint = "/v1/moderations"
  - const BatchNewParamsEndpointV1ImagesGenerations BatchNewParamsEndpoint = "/v1/images/generations"
  - const BatchNewParamsEndpointV1ImagesEdits BatchNewParamsEndpoint = "/v1/images/edits"
  - const BatchNewParamsEndpointV1Videos BatchNewParamsEndpoint = "/v1/videos"
- InputFileID param.Field[string]
  
  The ID of an uploaded file that contains requests for the new batch.
  
  See upload file for how to upload a file.
  
  Your input file must be formatted as a JSONL file, and must be uploaded with the purpose batch. The file can contain up to 50,000 requests, and can be up to 200 MB in size.
- Metadata param.Field[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.
- OutputExpiresAfter param.Field[BatchNewParamsOutputExpiresAfter]
  
  The expiration policy for the output and/or error file that are generated for a batch.
  - Anchor CreatedAt
    
    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.
    - const CreatedAtCreatedAt CreatedAt = "created_at"
  - Seconds int64
    
    The number of seconds after the anchor time that the file will expire. Must be between 3600 (1 hour) and 2592000 (30 days).

Returns

type Batch struct{…}
- ID string
- CompletionWindow string
  
  The time frame within which the batch should be processed.
- CreatedAt int64
  
  The Unix timestamp (in seconds) for when the batch was created.
- Endpoint string
  
  The OpenAI API endpoint used by the batch.
- InputFileID string
  
  The ID of the input file for the batch.
- Object Batch
  
  The object type, which is always batch.
  - const BatchBatch Batch = "batch"
- Status BatchStatus
  
  The current status of the batch.
  - const BatchStatusValidating BatchStatus = "validating"
  - const BatchStatusFailed BatchStatus = "failed"
  - const BatchStatusInProgress BatchStatus = "in_progress"
  - const BatchStatusFinalizing BatchStatus = "finalizing"
  - const BatchStatusCompleted BatchStatus = "completed"
  - const BatchStatusExpired BatchStatus = "expired"
  - const BatchStatusCancelling BatchStatus = "cancelling"
  - const BatchStatusCancelled BatchStatus = "cancelled"
- CancelledAt int64
  
  The Unix timestamp (in seconds) for when the batch was cancelled.
- CancellingAt int64
  
  The Unix timestamp (in seconds) for when the batch started cancelling.
- CompletedAt int64
  
  The Unix timestamp (in seconds) for when the batch was completed.
- ErrorFileID string
  
  The ID of the file containing the outputs of requests with errors.
- Errors BatchErrors
  - Data []BatchError
    - Code string
      
      An error code identifying the error type.
    - Line int64
      
      The line number of the input file where the error occurred, if applicable.
    - Message string
      
      A human-readable message providing more details about the error.
    - Param string
      
      The name of the parameter that caused the error, if applicable.
  - Object string
    
    The object type, which is always list.
- ExpiredAt int64
  
  The Unix timestamp (in seconds) for when the batch expired.
- ExpiresAt int64
  
  The Unix timestamp (in seconds) for when the batch will expire.
- FailedAt int64
  
  The Unix timestamp (in seconds) for when the batch failed.
- FinalizingAt int64
  
  The Unix timestamp (in seconds) for when the batch started finalizing.
- InProgressAt int64
  
  The Unix timestamp (in seconds) for when the batch started processing.
- 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.
- Model string
  
  Model ID used to process the batch, like gpt-5-2025-08-07. OpenAI offers a wide range of models with different capabilities, performance characteristics, and price points. Refer to the model guide to browse and compare available models.
- OutputFileID string
  
  The ID of the file containing the outputs of successfully executed requests.
- RequestCounts BatchRequestCounts
  
  The request counts for different statuses within the batch.
  - Completed int64
    
    Number of requests that have been completed successfully.
  - Failed int64
    
    Number of requests that have failed.
  - Total int64
    
    Total number of requests in the batch.
- Usage 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.
  - InputTokens int64
    
    The number of input tokens.
  - InputTokensDetails BatchUsageInputTokensDetails
    
    A detailed breakdown of the input tokens.
    - CachedTokens int64
      
      The number of tokens that were retrieved from the cache. More on prompt caching.
  - OutputTokens int64
    
    The number of output tokens.
  - OutputTokensDetails BatchUsageOutputTokensDetails
    
    A detailed breakdown of the output tokens.
    - ReasoningTokens int64
      
      The number of reasoning tokens.
  - TotalTokens int64
    
    The total number of tokens used.

Example

package main

import (
  "context"
  "fmt"

  "github.com/openai/openai-go"
  "github.com/openai/openai-go/option"
)

func main() {
  client := openai.NewClient(
    option.WithAPIKey("My API Key"),
  )
  batch, err := client.Batches.New(context.TODO(), openai.BatchNewParams{
    CompletionWindow: openai.BatchNewParamsCompletionWindow24h,
    Endpoint: openai.BatchNewParamsEndpointV1Responses,
    InputFileID: "input_file_id",
  })
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", 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
  }
}

Retrieve batch

client.Batches.Get(ctx, batchID) (*Batch, error)

get /batches/{batch_id}

Retrieves a batch.

Parameters

batchID string

Returns

type Batch struct{…}
- ID string
- CompletionWindow string
  
  The time frame within which the batch should be processed.
- CreatedAt int64
  
  The Unix timestamp (in seconds) for when the batch was created.
- Endpoint string
  
  The OpenAI API endpoint used by the batch.
- InputFileID string
  
  The ID of the input file for the batch.
- Object Batch
  
  The object type, which is always batch.
  - const BatchBatch Batch = "batch"
- Status BatchStatus
  
  The current status of the batch.
  - const BatchStatusValidating BatchStatus = "validating"
  - const BatchStatusFailed BatchStatus = "failed"
  - const BatchStatusInProgress BatchStatus = "in_progress"
  - const BatchStatusFinalizing BatchStatus = "finalizing"
  - const BatchStatusCompleted BatchStatus = "completed"
  - const BatchStatusExpired BatchStatus = "expired"
  - const BatchStatusCancelling BatchStatus = "cancelling"
  - const BatchStatusCancelled BatchStatus = "cancelled"
- CancelledAt int64
  
  The Unix timestamp (in seconds) for when the batch was cancelled.
- CancellingAt int64
  
  The Unix timestamp (in seconds) for when the batch started cancelling.
- CompletedAt int64
  
  The Unix timestamp (in seconds) for when the batch was completed.
- ErrorFileID string
  
  The ID of the file containing the outputs of requests with errors.
- Errors BatchErrors
  - Data []BatchError
    - Code string
      
      An error code identifying the error type.
    - Line int64
      
      The line number of the input file where the error occurred, if applicable.
    - Message string
      
      A human-readable message providing more details about the error.
    - Param string
      
      The name of the parameter that caused the error, if applicable.
  - Object string
    
    The object type, which is always list.
- ExpiredAt int64
  
  The Unix timestamp (in seconds) for when the batch expired.
- ExpiresAt int64
  
  The Unix timestamp (in seconds) for when the batch will expire.
- FailedAt int64
  
  The Unix timestamp (in seconds) for when the batch failed.
- FinalizingAt int64
  
  The Unix timestamp (in seconds) for when the batch started finalizing.
- InProgressAt int64
  
  The Unix timestamp (in seconds) for when the batch started processing.
- 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.
- Model string
  
  Model ID used to process the batch, like gpt-5-2025-08-07. OpenAI offers a wide range of models with different capabilities, performance characteristics, and price points. Refer to the model guide to browse and compare available models.
- OutputFileID string
  
  The ID of the file containing the outputs of successfully executed requests.
- RequestCounts BatchRequestCounts
  
  The request counts for different statuses within the batch.
  - Completed int64
    
    Number of requests that have been completed successfully.
  - Failed int64
    
    Number of requests that have failed.
  - Total int64
    
    Total number of requests in the batch.
- Usage 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.
  - InputTokens int64
    
    The number of input tokens.
  - InputTokensDetails BatchUsageInputTokensDetails
    
    A detailed breakdown of the input tokens.
    - CachedTokens int64
      
      The number of tokens that were retrieved from the cache. More on prompt caching.
  - OutputTokens int64
    
    The number of output tokens.
  - OutputTokensDetails BatchUsageOutputTokensDetails
    
    A detailed breakdown of the output tokens.
    - ReasoningTokens int64
      
      The number of reasoning tokens.
  - TotalTokens int64
    
    The total number of tokens used.

Example

package main

import (
  "context"
  "fmt"

  "github.com/openai/openai-go"
  "github.com/openai/openai-go/option"
)

func main() {
  client := openai.NewClient(
    option.WithAPIKey("My API Key"),
  )
  batch, err := client.Batches.Get(context.TODO(), "batch_id")
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", 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

client.Batches.Cancel(ctx, batchID) (*Batch, error)

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

batchID string

Returns

type Batch struct{…}
- ID string
- CompletionWindow string
  
  The time frame within which the batch should be processed.
- CreatedAt int64
  
  The Unix timestamp (in seconds) for when the batch was created.
- Endpoint string
  
  The OpenAI API endpoint used by the batch.
- InputFileID string
  
  The ID of the input file for the batch.
- Object Batch
  
  The object type, which is always batch.
  - const BatchBatch Batch = "batch"
- Status BatchStatus
  
  The current status of the batch.
  - const BatchStatusValidating BatchStatus = "validating"
  - const BatchStatusFailed BatchStatus = "failed"
  - const BatchStatusInProgress BatchStatus = "in_progress"
  - const BatchStatusFinalizing BatchStatus = "finalizing"
  - const BatchStatusCompleted BatchStatus = "completed"
  - const BatchStatusExpired BatchStatus = "expired"
  - const BatchStatusCancelling BatchStatus = "cancelling"
  - const BatchStatusCancelled BatchStatus = "cancelled"
- CancelledAt int64
  
  The Unix timestamp (in seconds) for when the batch was cancelled.
- CancellingAt int64
  
  The Unix timestamp (in seconds) for when the batch started cancelling.
- CompletedAt int64
  
  The Unix timestamp (in seconds) for when the batch was completed.
- ErrorFileID string
  
  The ID of the file containing the outputs of requests with errors.
- Errors BatchErrors
  - Data []BatchError
    - Code string
      
      An error code identifying the error type.
    - Line int64
      
      The line number of the input file where the error occurred, if applicable.
    - Message string
      
      A human-readable message providing more details about the error.
    - Param string
      
      The name of the parameter that caused the error, if applicable.
  - Object string
    
    The object type, which is always list.
- ExpiredAt int64
  
  The Unix timestamp (in seconds) for when the batch expired.
- ExpiresAt int64
  
  The Unix timestamp (in seconds) for when the batch will expire.
- FailedAt int64
  
  The Unix timestamp (in seconds) for when the batch failed.
- FinalizingAt int64
  
  The Unix timestamp (in seconds) for when the batch started finalizing.
- InProgressAt int64
  
  The Unix timestamp (in seconds) for when the batch started processing.
- 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.
- Model string
  
  Model ID used to process the batch, like gpt-5-2025-08-07. OpenAI offers a wide range of models with different capabilities, performance characteristics, and price points. Refer to the model guide to browse and compare available models.
- OutputFileID string
  
  The ID of the file containing the outputs of successfully executed requests.
- RequestCounts BatchRequestCounts
  
  The request counts for different statuses within the batch.
  - Completed int64
    
    Number of requests that have been completed successfully.
  - Failed int64
    
    Number of requests that have failed.
  - Total int64
    
    Total number of requests in the batch.
- Usage 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.
  - InputTokens int64
    
    The number of input tokens.
  - InputTokensDetails BatchUsageInputTokensDetails
    
    A detailed breakdown of the input tokens.
    - CachedTokens int64
      
      The number of tokens that were retrieved from the cache. More on prompt caching.
  - OutputTokens int64
    
    The number of output tokens.
  - OutputTokensDetails BatchUsageOutputTokensDetails
    
    A detailed breakdown of the output tokens.
    - ReasoningTokens int64
      
      The number of reasoning tokens.
  - TotalTokens int64
    
    The total number of tokens used.

Example

package main

import (
  "context"
  "fmt"

  "github.com/openai/openai-go"
  "github.com/openai/openai-go/option"
)

func main() {
  client := openai.NewClient(
    option.WithAPIKey("My API Key"),
  )
  batch, err := client.Batches.Cancel(context.TODO(), "batch_id")
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", 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

client.Batches.List(ctx, query) (*CursorPage[Batch], error)

get /batches

List your organization's batches.

Parameters

query BatchListParams
- After param.Field[string]
  
  A cursor for use in pagination. after is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list.
- Limit param.Field[int64]
  
  A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20.

Returns

type Batch struct{…}
- ID string
- CompletionWindow string
  
  The time frame within which the batch should be processed.
- CreatedAt int64
  
  The Unix timestamp (in seconds) for when the batch was created.
- Endpoint string
  
  The OpenAI API endpoint used by the batch.
- InputFileID string
  
  The ID of the input file for the batch.
- Object Batch
  
  The object type, which is always batch.
  - const BatchBatch Batch = "batch"
- Status BatchStatus
  
  The current status of the batch.
  - const BatchStatusValidating BatchStatus = "validating"
  - const BatchStatusFailed BatchStatus = "failed"
  - const BatchStatusInProgress BatchStatus = "in_progress"
  - const BatchStatusFinalizing BatchStatus = "finalizing"
  - const BatchStatusCompleted BatchStatus = "completed"
  - const BatchStatusExpired BatchStatus = "expired"
  - const BatchStatusCancelling BatchStatus = "cancelling"
  - const BatchStatusCancelled BatchStatus = "cancelled"
- CancelledAt int64
  
  The Unix timestamp (in seconds) for when the batch was cancelled.
- CancellingAt int64
  
  The Unix timestamp (in seconds) for when the batch started cancelling.
- CompletedAt int64
  
  The Unix timestamp (in seconds) for when the batch was completed.
- ErrorFileID string
  
  The ID of the file containing the outputs of requests with errors.
- Errors BatchErrors
  - Data []BatchError
    - Code string
      
      An error code identifying the error type.
    - Line int64
      
      The line number of the input file where the error occurred, if applicable.
    - Message string
      
      A human-readable message providing more details about the error.
    - Param string
      
      The name of the parameter that caused the error, if applicable.
  - Object string
    
    The object type, which is always list.
- ExpiredAt int64
  
  The Unix timestamp (in seconds) for when the batch expired.
- ExpiresAt int64
  
  The Unix timestamp (in seconds) for when the batch will expire.
- FailedAt int64
  
  The Unix timestamp (in seconds) for when the batch failed.
- FinalizingAt int64
  
  The Unix timestamp (in seconds) for when the batch started finalizing.
- InProgressAt int64
  
  The Unix timestamp (in seconds) for when the batch started processing.
- 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.
- Model string
  
  Model ID used to process the batch, like gpt-5-2025-08-07. OpenAI offers a wide range of models with different capabilities, performance characteristics, and price points. Refer to the model guide to browse and compare available models.
- OutputFileID string
  
  The ID of the file containing the outputs of successfully executed requests.
- RequestCounts BatchRequestCounts
  
  The request counts for different statuses within the batch.
  - Completed int64
    
    Number of requests that have been completed successfully.
  - Failed int64
    
    Number of requests that have failed.
  - Total int64
    
    Total number of requests in the batch.
- Usage 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.
  - InputTokens int64
    
    The number of input tokens.
  - InputTokensDetails BatchUsageInputTokensDetails
    
    A detailed breakdown of the input tokens.
    - CachedTokens int64
      
      The number of tokens that were retrieved from the cache. More on prompt caching.
  - OutputTokens int64
    
    The number of output tokens.
  - OutputTokensDetails BatchUsageOutputTokensDetails
    
    A detailed breakdown of the output tokens.
    - ReasoningTokens int64
      
      The number of reasoning tokens.
  - TotalTokens int64
    
    The total number of tokens used.

Example

package main

import (
  "context"
  "fmt"

  "github.com/openai/openai-go"
  "github.com/openai/openai-go/option"
)

func main() {
  client := openai.NewClient(
    option.WithAPIKey("My API Key"),
  )
  page, err := client.Batches.List(context.TODO(), openai.BatchListParams{

  })
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", page)
}

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

type Batch struct{…}
- ID string
- CompletionWindow string
  
  The time frame within which the batch should be processed.
- CreatedAt int64
  
  The Unix timestamp (in seconds) for when the batch was created.
- Endpoint string
  
  The OpenAI API endpoint used by the batch.
- InputFileID string
  
  The ID of the input file for the batch.
- Object Batch
  
  The object type, which is always batch.
  - const BatchBatch Batch = "batch"
- Status BatchStatus
  
  The current status of the batch.
  - const BatchStatusValidating BatchStatus = "validating"
  - const BatchStatusFailed BatchStatus = "failed"
  - const BatchStatusInProgress BatchStatus = "in_progress"
  - const BatchStatusFinalizing BatchStatus = "finalizing"
  - const BatchStatusCompleted BatchStatus = "completed"
  - const BatchStatusExpired BatchStatus = "expired"
  - const BatchStatusCancelling BatchStatus = "cancelling"
  - const BatchStatusCancelled BatchStatus = "cancelled"
- CancelledAt int64
  
  The Unix timestamp (in seconds) for when the batch was cancelled.
- CancellingAt int64
  
  The Unix timestamp (in seconds) for when the batch started cancelling.
- CompletedAt int64
  
  The Unix timestamp (in seconds) for when the batch was completed.
- ErrorFileID string
  
  The ID of the file containing the outputs of requests with errors.
- Errors BatchErrors
  - Data []BatchError
    - Code string
      
      An error code identifying the error type.
    - Line int64
      
      The line number of the input file where the error occurred, if applicable.
    - Message string
      
      A human-readable message providing more details about the error.
    - Param string
      
      The name of the parameter that caused the error, if applicable.
  - Object string
    
    The object type, which is always list.
- ExpiredAt int64
  
  The Unix timestamp (in seconds) for when the batch expired.
- ExpiresAt int64
  
  The Unix timestamp (in seconds) for when the batch will expire.
- FailedAt int64
  
  The Unix timestamp (in seconds) for when the batch failed.
- FinalizingAt int64
  
  The Unix timestamp (in seconds) for when the batch started finalizing.
- InProgressAt int64
  
  The Unix timestamp (in seconds) for when the batch started processing.
- 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.
- Model string
  
  Model ID used to process the batch, like gpt-5-2025-08-07. OpenAI offers a wide range of models with different capabilities, performance characteristics, and price points. Refer to the model guide to browse and compare available models.
- OutputFileID string
  
  The ID of the file containing the outputs of successfully executed requests.
- RequestCounts BatchRequestCounts
  
  The request counts for different statuses within the batch.
  - Completed int64
    
    Number of requests that have been completed successfully.
  - Failed int64
    
    Number of requests that have failed.
  - Total int64
    
    Total number of requests in the batch.
- Usage 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.
  - InputTokens int64
    
    The number of input tokens.
  - InputTokensDetails BatchUsageInputTokensDetails
    
    A detailed breakdown of the input tokens.
    - CachedTokens int64
      
      The number of tokens that were retrieved from the cache. More on prompt caching.
  - OutputTokens int64
    
    The number of output tokens.
  - OutputTokensDetails BatchUsageOutputTokensDetails
    
    A detailed breakdown of the output tokens.
    - ReasoningTokens int64
      
      The number of reasoning tokens.
  - TotalTokens int64
    
    The total number of tokens used.

Batch Error

type BatchError struct{…}
- Code string
  
  An error code identifying the error type.
- Line int64
  
  The line number of the input file where the error occurred, if applicable.
- Message string
  
  A human-readable message providing more details about the error.
- Param string
  
  The name of the parameter that caused the error, if applicable.

Batch Request Counts

type BatchRequestCounts struct{…}

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

Batch Usage

type BatchUsage struct{…}

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.
- InputTokens int64
  
  The number of input tokens.
- InputTokensDetails BatchUsageInputTokensDetails
  
  A detailed breakdown of the input tokens.
  - CachedTokens int64
    
    The number of tokens that were retrieved from the cache. More on prompt caching.
- OutputTokens int64
  
  The number of output tokens.
- OutputTokensDetails BatchUsageOutputTokensDetails
  
  A detailed breakdown of the output tokens.
  - ReasoningTokens int64
    
    The number of reasoning tokens.
- TotalTokens int64
  
  The total number of tokens used.

go/resources/batches/index.md +240 −24

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 - `Errors BatchErrors`136 - `Errors BatchErrors`

137 137

138 - `Data []any`138 - `Data []BatchError`

139

140 - `Code string`

141

142 An error code identifying the error type.

143

144 - `Line int64`

145

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

147

148 - `Message string`

149

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

151

152 - `Param string`

153

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

139 155

140 - `Object string`156 - `Object string`

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 - `RequestCounts any`200 - `RequestCounts BatchRequestCounts`

201

202 The request counts for different statuses within the batch.

203

204 - `Completed int64`

205

206 Number of requests that have been completed successfully.

207

208 - `Failed int64`

209

210 Number of requests that have failed.

211

212 - `Total int64`

213

214 Total number of requests in the batch.

185 215

186 - `Usage BatchUsage`216 - `Usage BatchUsage`

187 217

264 "error_file_id": "error_file_id",294 "error_file_id": "error_file_id",

265 "errors": {295 "errors": {

266 "data": [296 "data": [

267 {}297 {

298 "code": "code",

299 "line": 0,

300 "message": "message",

301 "param": "param"

302 }

268 ],303 ],

269 "object": "object"304 "object": "object"

270 },305 },

278 },313 },

279 "model": "model",314 "model": "model",

280 "output_file_id": "output_file_id",315 "output_file_id": "output_file_id",

281 "request_counts": {},316 "request_counts": {

317 "completed": 0,

318 "failed": 0,

319 "total": 0

320 },

282 "usage": {321 "usage": {

283 "input_tokens": 0,322 "input_tokens": 0,

284 "input_tokens_details": {323 "input_tokens_details": {

299 338

300**get** `/batches/{batch_id}`339**get** `/batches/{batch_id}`

301 340

302Retrieve batch341Retrieves a batch.

303 342

304### Parameters343### Parameters

305 344

371 410

372 - `Errors BatchErrors`411 - `Errors BatchErrors`

373 412

374 - `Data []any`413 - `Data []BatchError`

414

415 - `Code string`

416

417 An error code identifying the error type.

418

419 - `Line int64`

420

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

422

423 - `Message string`

424

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

426

427 - `Param string`

428

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

375 430

376 - `Object string`431 - `Object string`

377 432

417 472

418 The ID of the file containing the outputs of successfully executed requests.473 The ID of the file containing the outputs of successfully executed requests.

419 474

420 - `RequestCounts any`475 - `RequestCounts BatchRequestCounts`

476

477 The request counts for different statuses within the batch.

478

479 - `Completed int64`

480

481 Number of requests that have been completed successfully.

482

483 - `Failed int64`

484

485 Number of requests that have failed.

486

487 - `Total int64`

488

489 Total number of requests in the batch.

421 490

422 - `Usage BatchUsage`491 - `Usage BatchUsage`

423 492

496 "error_file_id": "error_file_id",565 "error_file_id": "error_file_id",

497 "errors": {566 "errors": {

498 "data": [567 "data": [

499 {}568 {

569 "code": "code",

570 "line": 0,

571 "message": "message",

572 "param": "param"

573 }

500 ],574 ],

501 "object": "object"575 "object": "object"

502 },576 },

510 },584 },

511 "model": "model",585 "model": "model",

512 "output_file_id": "output_file_id",586 "output_file_id": "output_file_id",

513 "request_counts": {},587 "request_counts": {

588 "completed": 0,

589 "failed": 0,

590 "total": 0

591 },

514 "usage": {592 "usage": {

515 "input_tokens": 0,593 "input_tokens": 0,

516 "input_tokens_details": {594 "input_tokens_details": {

531 609

532**post** `/batches/{batch_id}/cancel`610**post** `/batches/{batch_id}/cancel`

533 611

534Cancel batch612Cancels 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.

535 613

536### Parameters614### Parameters

537 615

603 681

604 - `Errors BatchErrors`682 - `Errors BatchErrors`

605 683

606 - `Data []any`684 - `Data []BatchError`

685

686 - `Code string`

687

688 An error code identifying the error type.

689

690 - `Line int64`

691

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

693

694 - `Message string`

695

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

697

698 - `Param string`

699

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

607 701

608 - `Object string`702 - `Object string`

609 703

649 743

650 The ID of the file containing the outputs of successfully executed requests.744 The ID of the file containing the outputs of successfully executed requests.

651 745

652 - `RequestCounts any`746 - `RequestCounts BatchRequestCounts`

747

748 The request counts for different statuses within the batch.

749

750 - `Completed int64`

751

752 Number of requests that have been completed successfully.

753

754 - `Failed int64`

755

756 Number of requests that have failed.

757

758 - `Total int64`

759

760 Total number of requests in the batch.

653 761

654 - `Usage BatchUsage`762 - `Usage BatchUsage`

655 763

728 "error_file_id": "error_file_id",836 "error_file_id": "error_file_id",

729 "errors": {837 "errors": {

730 "data": [838 "data": [

731 {}839 {

840 "code": "code",

841 "line": 0,

842 "message": "message",

843 "param": "param"

844 }

732 ],845 ],

733 "object": "object"846 "object": "object"

734 },847 },

742 },855 },

743 "model": "model",856 "model": "model",

744 "output_file_id": "output_file_id",857 "output_file_id": "output_file_id",

745 "request_counts": {},858 "request_counts": {

859 "completed": 0,

860 "failed": 0,

861 "total": 0

862 },

746 "usage": {863 "usage": {

747 "input_tokens": 0,864 "input_tokens": 0,

748 "input_tokens_details": {865 "input_tokens_details": {

763 880

764**get** `/batches`881**get** `/batches`

765 882

766List batches883List your organization's batches.

767 884

768### Parameters885### Parameters

769 886

843 960

844 - `Errors BatchErrors`961 - `Errors BatchErrors`

845 962

846 - `Data []any`963 - `Data []BatchError`

964

965 - `Code string`

966

967 An error code identifying the error type.

968

969 - `Line int64`

970

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

972

973 - `Message string`

974

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

976

977 - `Param string`

978

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

847 980

848 - `Object string`981 - `Object string`

849 982

889 1022

890 The ID of the file containing the outputs of successfully executed requests.1023 The ID of the file containing the outputs of successfully executed requests.

891 1024

892 - `RequestCounts any`1025 - `RequestCounts BatchRequestCounts`

1026

1027 The request counts for different statuses within the batch.

1028

1029 - `Completed int64`

1030

1031 Number of requests that have been completed successfully.

1032

1033 - `Failed int64`

1034

1035 Number of requests that have failed.

1036

1037 - `Total int64`

1038

1039 Total number of requests in the batch.

893 1040

894 - `Usage BatchUsage`1041 - `Usage BatchUsage`

895 1042

972 "error_file_id": "error_file_id",1119 "error_file_id": "error_file_id",

973 "errors": {1120 "errors": {

974 "data": [1121 "data": [

975 {}1122 {

1123 "code": "code",

1124 "line": 0,

1125 "message": "message",

1126 "param": "param"

1127 }

976 ],1128 ],

977 "object": "object"1129 "object": "object"

978 },1130 },

986 },1138 },

987 "model": "model",1139 "model": "model",

988 "output_file_id": "output_file_id",1140 "output_file_id": "output_file_id",

989 "request_counts": {},1141 "request_counts": {

1142 "completed": 0,

1143 "failed": 0,

1144 "total": 0

1145 },

990 "usage": {1146 "usage": {

991 "input_tokens": 0,1147 "input_tokens": 0,

992 "input_tokens_details": {1148 "input_tokens_details": {

1075 1231

1076 - `Errors BatchErrors`1232 - `Errors BatchErrors`

1077 1233

1078 - `Data []any`1234 - `Data []BatchError`

1235

1236 - `Code string`

1237

1238 An error code identifying the error type.

1239

1240 - `Line int64`

1241

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

1243

1244 - `Message string`

1245

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

1247

1248 - `Param string`

1249

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

1079 1251

1080 - `Object string`1252 - `Object string`

1081 1253

1121 1293

1122 The ID of the file containing the outputs of successfully executed requests.1294 The ID of the file containing the outputs of successfully executed requests.

1123 1295

1124 - `RequestCounts any`1296 - `RequestCounts BatchRequestCounts`

1297

1298 The request counts for different statuses within the batch.

1299

1300 - `Completed int64`

1301

1302 Number of requests that have been completed successfully.

1303

1304 - `Failed int64`

1305

1306 Number of requests that have failed.

1307

1308 - `Total int64`

1309

1310 Total number of requests in the batch.

1125 1311

1126 - `Usage BatchUsage`1312 - `Usage BatchUsage`

1127 1313

1160 1346

1161### Batch Error1347### Batch Error

1162 1348

1163- `type BatchError interface{…}`1349- `type BatchError struct{…}`

1350

1351 - `Code string`

1352

1353 An error code identifying the error type.

1354

1355 - `Line int64`

1356

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

1358

1359 - `Message string`

1360

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

1362

1363 - `Param string`

1364

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

1164 1366

1165### Batch Request Counts1367### Batch Request Counts

1166 1368

1167- `type BatchRequestCounts interface{…}`1369- `type BatchRequestCounts struct{…}`

1370

1371 The request counts for different statuses within the batch.

1372

1373 - `Completed int64`

1374

1375 Number of requests that have been completed successfully.

1376

1377 - `Failed int64`

1378

1379 Number of requests that have failed.

1380

1381 - `Total int64`

1382

1383 Total number of requests in the batch.

1168 1384

1169### Batch Usage1385### Batch Usage

1170 1386

go/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