Share via

Batch - Create

Service:
Azure AI Services
API Version:
2024-10-21

Creates and executes a batch from an uploaded file of requests. Response includes details of the enqueued job including job status. The ID of the result file is added to the response once complete.

POST {endpoint}/openai/batches?api-version=2024-10-21

URI Parameters

Name In Required Type Description
endpoint
 path True

string (url)

Supported Cognitive Services endpoints (protocol and hostname, for example: https://aoairesource.openai.azure.com. Replace "aoairesource" with your Azure OpenAI account name).
api-version
 query True

string

The requested API version.

Request Header

Name Required Type Description
api-key True

string

Provide your Cognitive Services Azure OpenAI account key here.

Request Body

Name Required Type Description
completion_window True

string

The time frame within which the batch should be processed.
endpoint True

string

The API endpoint used by the batch.
input_file_id True

string

minLength: 1

The ID if the input file for the batch.
metadata

object

A set of key-value pairs that can be attached to the batch. This can be useful for storing additional information about the batch in a structured format.

Responses

Name Type Description
200 OK

Batch

The batch has been successfully created.
Other Status Codes

ErrorResponse

An error occurred.

Security

api-key

Provide your Cognitive Services Azure OpenAI account key here.

Type: apiKey
In: header

Examples

Creating a batch.

Sample request

POST https://aoairesource.openai.azure.com/openai/batches?api-version=2024-10-21

Sample response

Status code:
200 
{
  "object": "batch",
  "id": "batch_72a2792ef7d24ba7b82c7fe4a37e379f",
  "endpoint": "/chat/completions",
  "errors": null,
  "input_file_id": "file-b4fa7277f3eb4722ac18b90f46102c3f",
  "completion_window": "24h",
  "status": "validating",
  "output_file_id": null,
  "error_file_id": null,
  "created_at": 1646126127,
  "in_progress_at": null,
  "expires_at": null,
  "finalizing_at": null,
  "completed_at": null,
  "failed_at": null,
  "expired_at": null,
  "cancelling_at": null,
  "cancelled_at": null,
  "request_counts": {
    "total": 0,
    "completed": 0,
    "failed": 0
  },
  "metadata": {
    "batch_description": "Evaluation job"
  }
}

Definitions

Name Description
Batch

Batch
BatchCreateRequest

BatchCreateRequest
BatchErrorData

BatchErrorData
BatchErrors

BatchErrors
BatchRequestCounts

BatchRequestCounts
BatchStatus

BatchStatus
Error

Error
ErrorCode

ErrorCode
ErrorResponse

ErrorResponse
InnerError

InnerError
InnerErrorCode

InnerErrorCode
TypeDiscriminator

TypeDiscriminator

Batch

Object

Batch

Name Type Description
cancelled_at

integer (unixtime)

A timestamp when this batch was cancelled (in unix epochs).
cancelling_at

integer (unixtime)

A timestamp when this batch started cancelling (in unix epochs).
completed_at

integer (unixtime)

A timestamp when this batch was completed (in unix epochs).
completion_window

string

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

integer (unixtime)

A timestamp when this batch was created (in unix epochs).
endpoint

string

The API endpoint used by the batch.
error_file_id

string

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

BatchErrors

BatchErrors
For batches that have failed, this will contain more information on the cause of the failures.
expired_at

integer (unixtime)

A timestamp when this batch expired (in unix epochs).
expires_at

integer (unixtime)

A timestamp when this batch will expire (in unix epochs).
failed_at

integer (unixtime)

A timestamp when this batch failed (in unix epochs).
finalizing_at

integer (unixtime)

A timestamp when this batch started finalizing (in unix epochs).
id

string

The identity of this item.
in_progress_at

integer (unixtime)

A timestamp when this batch started progressing (in unix epochs).
input_file_id

string

minLength: 1

The ID of the input file for the batch.
metadata

object

A set of key-value pairs that can be attached to the batch. This can be useful for storing additional information about the batch in a structured format.
object

TypeDiscriminator

TypeDiscriminator
Defines the type of an object.
output_file_id

string

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

BatchRequestCounts

BatchRequestCounts
The request counts for different statuses within the batch.
status

BatchStatus

BatchStatus
The status of a batch.

BatchCreateRequest

Object

BatchCreateRequest

Name Type Description
completion_window

string

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

string

The API endpoint used by the batch.
input_file_id

string

minLength: 1

The ID if the input file for the batch.
metadata

object

A set of key-value pairs that can be attached to the batch. This can be useful for storing additional information about the batch in a structured format.

BatchErrorData

Object

BatchErrorData

Name Type Description
code

string

An error code identifying the error type.
line

string

The line number of the input file where the error occurred, if applicable (can be null).
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 (can be null).

BatchErrors

Object

BatchErrors

Name Type Description
data

BatchErrorData

BatchErrorData
Error information for a failure in batch.
object

string

The type of the errors object. This is always 'list'.

BatchRequestCounts

Object

BatchRequestCounts

Name Type Description
completed

integer

The number of requests in the batch that have been completed successfully.
failed

integer

The number of requests in the batch that have failed.
total

integer

The total number of requests in the batch.

BatchStatus

Enumeration

BatchStatus

Value Description
validating

The input file is being validated before the batch can begin.
failed

The input file has failed the validation process.
in_progress

The input file was successfully validated and the batch is currently being executed.
finalizing

The batch has completed and the results are being prepared.
completed

The batch has been completed and the results are ready.
expired

The batch was not able to complete within the 24-hour time window.
cancelling

Cancellation of the batch has been initiated.
cancelled

The batch was cancelled.

Error

Object

Error

Name Type Description
code

ErrorCode

ErrorCode
Error codes as defined in the Microsoft REST guidelines (https://github.com/microsoft/api-guidelines/blob/vNext/Guidelines.md#7102-error-condition-responses).
details

Error[]

The error details if available.
innererror

InnerError

InnerError
Inner error as defined in the Microsoft REST guidelines (https://github.com/microsoft/api-guidelines/blob/vNext/Guidelines.md#7102-error-condition-responses).
message

string

minLength: 1

The message of this error.
target

string

The location where the error happened if available.

ErrorCode

Enumeration

ErrorCode

Value Description
conflict

The requested operation conflicts with the current resource state.
invalidPayload

The request data is invalid for this operation.
forbidden

The operation is forbidden for the current user/api key.
notFound

The resource is not found.
unexpectedEntityState

The operation cannot be executed in the current resource's state.
itemDoesAlreadyExist

The item does already exist.
serviceUnavailable

The service is currently not available.
internalFailure

Internal error. Please retry.
quotaExceeded

Quota exceeded.
jsonlValidationFailed

Validation of jsonl data failed.
fileImportFailed

Import of file failed.
tooManyRequests

Too many requests. Please retry later.
unauthorized

The current user/api key is not authorized for the operation.
contentFilter

Image generation failed as a result of our safety system.

ErrorResponse

Object

ErrorResponse

Name Type Description
error

Error

Error
Error content as defined in the Microsoft REST guidelines (https://github.com/microsoft/api-guidelines/blob/vNext/Guidelines.md#7102-error-condition-responses).

InnerError

Object

InnerError

Name Type Description
code

InnerErrorCode

InnerErrorCode
Inner error codes as defined in the Microsoft REST guidelines (https://github.com/microsoft/api-guidelines/blob/vNext/Guidelines.md#7102-error-condition-responses).
innererror

InnerError

InnerError
Inner error as defined in the Microsoft REST guidelines (https://github.com/microsoft/api-guidelines/blob/vNext/Guidelines.md#7102-error-condition-responses).

InnerErrorCode

Enumeration

InnerErrorCode

Value Description
invalidPayload

The request data is invalid for this operation.

TypeDiscriminator

Enumeration

TypeDiscriminator

Value Description
list

This object represents a list of other objects.
fine_tuning.job

This object represents a fine tune job.
file

This object represents a file.
fine_tuning.job.event

This object represents an event of a fine tuning job.
fine_tuning.job.checkpoint

This object represents a checkpoint of a fine tuning job.
model

This object represents a model (can be a base model or fine tune job result).
batch

This object represents a batch.
upload

This object represents a file upload.
upload.part

This object represents part of a file upload.