Skip to content
For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.
Primary navigation
Theme

List batches

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

List your organization’s batches.

List batches

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 example
{
  "object": "list",
  "data": [
    {
      "id": "batch_abc123",
      "object": "batch",
      "endpoint": "/v1/chat/completions",
      "errors": null,
      "input_file_id": "file-abc123",
      "completion_window": "24h",
      "status": "completed",
      "output_file_id": "file-cvaTdG",
      "error_file_id": "file-HOWS94",
      "created_at": 1711471533,
      "in_progress_at": 1711471538,
      "expires_at": 1711557933,
      "finalizing_at": 1711493133,
      "completed_at": 1711493163,
      "failed_at": null,
      "expired_at": null,
      "cancelling_at": null,
      "cancelled_at": null,
      "request_counts": {
        "total": 100,
        "completed": 95,
        "failed": 5
      },
      "metadata": {
        "customer_id": "user_123456789",
        "batch_description": "Nightly job"
      }
    }
  ],
  "first_id": "batch_abc123",
  "last_id": "batch_abc123",
  "has_more": false
}
Parameters
query BatchListParams
After param.Field[string]
Optional

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]
Optional

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.

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

Status BatchStatus

The current status of the batch.

CancelledAt int64
Optional

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

formatunixtime
CancellingAt int64
Optional

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

formatunixtime
CompletedAt int64
Optional

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

formatunixtime
ErrorFileID string
Optional

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

Errors BatchErrors
Optional
ExpiredAt int64
Optional

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

formatunixtime
ExpiresAt int64
Optional

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

formatunixtime
FailedAt int64
Optional

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

formatunixtime
FinalizingAt int64
Optional

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

formatunixtime
InProgressAt int64
Optional

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

formatunixtime
Metadata Metadata
Optional

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
Optional

Model ID used to process the batch, like gpt-6-astra. 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
Optional

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

RequestCounts BatchRequestCounts
Optional

The request counts for different statuses within the batch.

Usage BatchUsage
Optional

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.

Returns Examples
Response example
{
  "object": "list",
  "data": [
    {
      "id": "batch_abc123",
      "object": "batch",
      "endpoint": "/v1/chat/completions",
      "errors": null,
      "input_file_id": "file-abc123",
      "completion_window": "24h",
      "status": "completed",
      "output_file_id": "file-cvaTdG",
      "error_file_id": "file-HOWS94",
      "created_at": 1711471533,
      "in_progress_at": 1711471538,
      "expires_at": 1711557933,
      "finalizing_at": 1711493133,
      "completed_at": 1711493163,
      "failed_at": null,
      "expired_at": null,
      "cancelling_at": null,
      "cancelled_at": null,
      "request_counts": {
        "total": 100,
        "completed": 95,
        "failed": 5
      },
      "metadata": {
        "customer_id": "user_123456789",
        "batch_description": "Nightly job"
      }
    }
  ],
  "first_id": "batch_abc123",
  "last_id": "batch_abc123",
  "has_more": false
}