Skip to main content
Reference for the objects returned by the Batch API.

​
The Batch object

Most batch endpoints return a Batch object describing a batch job.
FieldTypeDescription
idstringThe batch identifier.
objectstringThe object type, always "batch".
endpointstringThe endpoint the batch runs against. Must match the url used on every line of the input file.
errorsobjectOptional. Validation errors for the batch. See errors.
input_file_idstringThe id of the input file for the batch.
completion_windowstringThe time window after which the batch expires. Currently only "24h" is supported.
statusstringThe current status of the batch. See Batch status.
output_file_idstringThe id of the file containing the outputs of successfully executed requests.
error_file_idstringThe id of the file containing the outputs of requests that failed (failed lines).
created_atintegerUnix timestamp (in seconds) for when the batch was created.
in_progress_atintegerUnix timestamp for when the batch started processing. null until reached.
expires_atintegerUnix timestamp for when the batch will expire. null until reached.
finalizing_atintegerUnix timestamp for when the batch started finalizing. null until reached.
completed_atintegerUnix timestamp for when the batch completed. null until reached.
failed_atintegerUnix timestamp for when the batch failed. null until reached.
expired_atintegerUnix timestamp for when the batch expired. null until reached.
cancelling_atintegerUnix timestamp for when the batch started cancelling. null until reached.
cancelled_atintegerUnix timestamp for when the batch was cancelled. null until reached.
request_countsobjectOptional. The counts of requests by status within the batch. See request_counts.
metadataobjectUp to 16 key–value string pairs, where each key is a string of up to 64 characters and each value is a string of up to 512 characters.
modelstringOptional. The model the inference is run against.
usageobjectOptional. Token usage statistics for the batch. See The BatchUsage object.

​
Batch status

A batch moves through the following statuses:
StatusMeaning
validatingThe input file is being validated before the batch starts.
in_progressValidation passed and requests are running.
finalizingAll requests are done; the output files are being assembled.
completedThe batch finished; results are ready to download.
failedValidation failed. The errors field of the Batch object describes why the file failed.
expiredNot all requests could finish within the 24-hour window; the finished ones are still written to the output file.
cancellingThe batch is being cancelled. This status may last for some time while in-flight requests finish.
cancelledThe batch has been cancelled successfully.

​
errors

FieldTypeDescription
objectstringThe object type, always "list".
dataarrayOptional. An array of error objects, each with the following optional fields:
FieldTypeDescription
codestringOptional. A machine-readable error code.
lineintegerOptional. The line of the input file the error refers to.
messagestringOptional. A human-readable description of the error.
paramstringOptional. The parameter the error relates to.

​
request_counts

FieldTypeDescription
totalintegerThe total number of requests in the batch.
completedintegerThe number of requests that have completed successfully.
failedintegerThe number of requests that have failed.

​
The BatchUsage object

Token usage statistics aggregated across all requests in the batch.
FieldTypeDescription
input_tokensintegerThe total number of input (prompt) tokens across the batch.
input_tokens_detailsobjectA breakdown of the input tokens. Contains cached_tokens, and may contain additional fields.
output_tokensintegerThe total number of output (completion) tokens across the batch.
output_tokens_detailsobjectA breakdown of the output tokens. Contains reasoning_tokens, and may contain additional fields.
total_tokensintegerThe total number of tokens used (input + output).

​
Example

Batch object of a completed batch: 
{
  "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_out456",
  "error_file_id": null,
  "created_at": 1711471533,
  "in_progress_at": 1711471538,
  "expires_at": null,
  "finalizing_at": 1711475133,
  "completed_at": 1711475134,
  "failed_at": null,
  "expired_at": null,
  "cancelling_at": null,
  "cancelled_at": null,
  "request_counts": {
    "total": 100,
    "completed": 100,
    "failed": 0
  },
  "metadata": {
    "description": "nightly eval run"
  },
  "model": "deepseek-ai/DeepSeek-V3",
  "usage": {
    "input_tokens": 12000,
    "input_tokens_details": {
      "cached_tokens": 0
    },
    "output_tokens": 8000,
    "output_tokens_details": {
      "reasoning_tokens": 0
    },
    "total_tokens": 20000
  }
}