Azure OpenAI batch

API Version: v1

Server: {endpoint}/openai/v1 — Azure AI Foundry Models APIs

Server Variables:

Variable Default Description
endpoint A supported Azure AI Foundry Models APIs endpoint, including protocol and hostname.
For example:
https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/).

Authentication

ApiKeyAuth (API Key)

Pass your API key in the api-key header.

ApiKeyAuth_ (API Key)

Pass your API key in the authorization header.

OAuth2Auth (OAuth 2.0)

Flow: implicit

Authorization URL: https://login.microsoftonline.com/common/oauth2/v2.0/authorize

Scopes:

  • https://cognitiveservices.azure.com/.default

Security Requirements

Endpoints accept any one of the following authentication methods:

  1. ApiKeyAuth
  2. ApiKeyAuth_
  3. OAuth2Auth (scopes: https://cognitiveservices.azure.com/.default)

Create batch

POST {endpoint}/openai/v1/batches

Creates and executes a batch from an uploaded file of requests

URI Parameters

Name In Required Type Description
endpoint server Yes string A supported Azure AI Foundry Models APIs endpoint, including protocol and hostname.
For example:
https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/).
api-version query No string
Possible values: v1, preview		 The explicit Azure AI Foundry Models API version to use for this request.
v1 if not otherwise specified.

Request Header

Name Required Type Description
accept Yes string
Possible values: application/json

Request Body

Content-Type: application/json

Name Type Description Required Default
completion_window enum The time frame within which the batch should be processed. Currently only 24h is supported.
Possible values: 24h		 Yes
endpoint enum The endpoint to be used for all requests in the batch. Currently /v1/chat/completions is supported.
Possible values: /v1/chat/completions, /v1/embeddings		 Yes
input_file_id string The ID of an uploaded file that contains requests for the new batch.



Your input file must be formatted as a JSONL file,
and must be uploaded with the purpose batch.		 No

Responses

Status Code: 201

Description: The request has succeeded and a new resource has been created as a result.

Content-Type Type Description
application/json object
Name Type Description Required Default
cancelled_at integer (unixtime) The Unix timestamp (in seconds) for when the batch was cancelled. No
cancelling_at integer (unixtime) The Unix timestamp (in seconds) for when the batch started cancelling. No
completed_at integer (unixtime) The Unix timestamp (in seconds) for when the batch was completed. No
completion_window string The time frame within which the batch should be processed. Yes
created_at integer (unixtime) The Unix timestamp (in seconds) for when the batch was created. Yes
endpoint string The OpenAI API endpoint used by the batch. Yes
error_file_id string The ID of the file containing the outputs of requests with errors. No
errors OpenAI.BatchErrors No
expired_at integer (unixtime) The Unix timestamp (in seconds) for when the batch expired. No
expires_at integer (unixtime) The Unix timestamp (in seconds) for when the batch will expire. No
failed_at integer (unixtime) The Unix timestamp (in seconds) for when the batch failed. No
finalizing_at integer (unixtime) The Unix timestamp (in seconds) for when the batch started finalizing. No
id string Yes
in_progress_at integer (unixtime) The Unix timestamp (in seconds) for when the batch started processing. No
input_file_id string or null No
metadata OpenAI.Metadata or null No
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.		 No
object enum The object type, which is always batch.
Possible values: batch		 Yes
output_file_id string The ID of the file containing the outputs of successfully executed requests. No
request_counts OpenAI.BatchRequestCounts No
└─ completed integer Yes
└─ failed integer Yes
└─ total integer Yes
status enum The current status of the batch.
Possible values: validating, failed, in_progress, finalizing, completed, expired, cancelling, cancelled		 Yes
usage OpenAI.BatchUsage No
└─ input_tokens integer Yes
└─ input_tokens_details OpenAI.BatchUsageInputTokensDetails Yes
└─ output_tokens integer Yes
└─ output_tokens_details OpenAI.BatchUsageOutputTokensDetails Yes
└─ total_tokens integer Yes

Response Headers:

Header Type Description
apim-request-id string A request ID used for troubleshooting purposes.

Status Code: default

Description: An unexpected error response.

Content-Type Type Description
application/json object
Name Type Description Required Default
code string or null Yes
inner_error No
message string Yes
param string or null No
type string No

Response Headers:

Header Type Description
apim-request-id string A request ID used for troubleshooting purposes.

List batches

GET {endpoint}/openai/v1/batches

List your organization's batches.

URI Parameters

Name In Required Type Description
endpoint server Yes string A supported Azure AI Foundry Models APIs endpoint, including protocol and hostname.
For example:
https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/).
api-version query No string
Possible values: v1, preview		 The explicit Azure AI Foundry Models API version to use for this request.
v1 if not otherwise specified.
after query No 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.
Serialization: explode: false
limit query No integer (int32) A limit on the number of objects to be returned. Limit can range between 1 and 100, and the
default is 20.
Serialization: explode: false

Request Header

Name Required Type Description
accept Yes string
Possible values: application/json

Responses

Status Code: 200

Description: The request has succeeded.

Content-Type Type Description
application/json OpenAI.ListBatchesResponse

Response Headers:

Header Type Description
apim-request-id string A request ID used for troubleshooting purposes.

Status Code: default

Description: An unexpected error response.

Content-Type Type Description
application/json object
Name Type Description Required Default
code string or null Yes
inner_error No
message string Yes
param string or null No
type string No

Response Headers:

Header Type Description
apim-request-id string A request ID used for troubleshooting purposes.

Retrieve batch

GET {endpoint}/openai/v1/batches/{batch_id}

Retrieves a batch.

URI Parameters

Name In Required Type Description
endpoint server Yes string A supported Azure AI Foundry Models APIs endpoint, including protocol and hostname.
For example:
https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/).
api-version query No string
Possible values: v1, preview		 The explicit Azure AI Foundry Models API version to use for this request.
v1 if not otherwise specified.
batch_id path Yes string The ID of the batch to retrieve.

Request Header

Name Required Type Description
accept Yes string
Possible values: application/json

Responses

Status Code: 200

Description: The request has succeeded.

Content-Type Type Description
application/json object
Name Type Description Required Default
cancelled_at integer (unixtime) The Unix timestamp (in seconds) for when the batch was cancelled. No
cancelling_at integer (unixtime) The Unix timestamp (in seconds) for when the batch started cancelling. No
completed_at integer (unixtime) The Unix timestamp (in seconds) for when the batch was completed. No
completion_window string The time frame within which the batch should be processed. Yes
created_at integer (unixtime) The Unix timestamp (in seconds) for when the batch was created. Yes
endpoint string The OpenAI API endpoint used by the batch. Yes
error_file_id string The ID of the file containing the outputs of requests with errors. No
errors OpenAI.BatchErrors No
expired_at integer (unixtime) The Unix timestamp (in seconds) for when the batch expired. No
expires_at integer (unixtime) The Unix timestamp (in seconds) for when the batch will expire. No
failed_at integer (unixtime) The Unix timestamp (in seconds) for when the batch failed. No
finalizing_at integer (unixtime) The Unix timestamp (in seconds) for when the batch started finalizing. No
id string Yes
in_progress_at integer (unixtime) The Unix timestamp (in seconds) for when the batch started processing. No
input_file_id string or null No
metadata OpenAI.Metadata or null No
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.		 No
object enum The object type, which is always batch.
Possible values: batch		 Yes
output_file_id string The ID of the file containing the outputs of successfully executed requests. No
request_counts OpenAI.BatchRequestCounts No
└─ completed integer Yes
└─ failed integer Yes
└─ total integer Yes
status enum The current status of the batch.
Possible values: validating, failed, in_progress, finalizing, completed, expired, cancelling, cancelled		 Yes
usage OpenAI.BatchUsage No
└─ input_tokens integer Yes
└─ input_tokens_details OpenAI.BatchUsageInputTokensDetails Yes
└─ output_tokens integer Yes
└─ output_tokens_details OpenAI.BatchUsageOutputTokensDetails Yes
└─ total_tokens integer Yes

Response Headers:

Header Type Description
apim-request-id string A request ID used for troubleshooting purposes.

Status Code: default

Description: An unexpected error response.

Content-Type Type Description
application/json object
Name Type Description Required Default
code string or null Yes
inner_error No
message string Yes
param string or null No
type string No

Response Headers:

Header Type Description
apim-request-id string A request ID used for troubleshooting purposes.

Cancel batch

POST {endpoint}/openai/v1/batches/{batch_id}/cancel

Cancels an in-progress batch.

URI Parameters

Name In Required Type Description
endpoint server Yes string A supported Azure AI Foundry Models APIs endpoint, including protocol and hostname.
For example:
https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/).
api-version query No string
Possible values: v1, preview		 The explicit Azure AI Foundry Models API version to use for this request.
v1 if not otherwise specified.
batch_id path Yes string The ID of the batch to cancel.

Request Header

Name Required Type Description
accept Yes string
Possible values: application/json

Responses

Status Code: 200

Description: The request has succeeded.

Content-Type Type Description
application/json object
Name Type Description Required Default
cancelled_at integer (unixtime) The Unix timestamp (in seconds) for when the batch was cancelled. No
cancelling_at integer (unixtime) The Unix timestamp (in seconds) for when the batch started cancelling. No
completed_at integer (unixtime) The Unix timestamp (in seconds) for when the batch was completed. No
completion_window string The time frame within which the batch should be processed. Yes
created_at integer (unixtime) The Unix timestamp (in seconds) for when the batch was created. Yes
endpoint string The OpenAI API endpoint used by the batch. Yes
error_file_id string The ID of the file containing the outputs of requests with errors. No
errors OpenAI.BatchErrors No
expired_at integer (unixtime) The Unix timestamp (in seconds) for when the batch expired. No
expires_at integer (unixtime) The Unix timestamp (in seconds) for when the batch will expire. No
failed_at integer (unixtime) The Unix timestamp (in seconds) for when the batch failed. No
finalizing_at integer (unixtime) The Unix timestamp (in seconds) for when the batch started finalizing. No
id string Yes
in_progress_at integer (unixtime) The Unix timestamp (in seconds) for when the batch started processing. No
input_file_id string or null No
metadata OpenAI.Metadata or null No
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.		 No
object enum The object type, which is always batch.
Possible values: batch		 Yes
output_file_id string The ID of the file containing the outputs of successfully executed requests. No
request_counts OpenAI.BatchRequestCounts No
└─ completed integer Yes
└─ failed integer Yes
└─ total integer Yes
status enum The current status of the batch.
Possible values: validating, failed, in_progress, finalizing, completed, expired, cancelling, cancelled		 Yes
usage OpenAI.BatchUsage No
└─ input_tokens integer Yes
└─ input_tokens_details OpenAI.BatchUsageInputTokensDetails Yes
└─ output_tokens integer Yes
└─ output_tokens_details OpenAI.BatchUsageOutputTokensDetails Yes
└─ total_tokens integer Yes

Response Headers:

Header Type Description
apim-request-id string A request ID used for troubleshooting purposes.

Status Code: default

Description: An unexpected error response.

Content-Type Type Description
application/json object
Name Type Description Required Default
code string or null Yes
inner_error No
message string Yes
param string or null No
type string No

Response Headers:

Header Type Description
apim-request-id string A request ID used for troubleshooting purposes.

Components

AzureAIFoundryModelsApiVersion

Property Value
Type string
Values v1
preview

OpenAI.Batch

Name Type Description Required Default
cancelled_at integer (unixtime) The Unix timestamp (in seconds) for when the batch was cancelled. No
cancelling_at integer (unixtime) The Unix timestamp (in seconds) for when the batch started cancelling. No
completed_at integer (unixtime) The Unix timestamp (in seconds) for when the batch was completed. No
completion_window string The time frame within which the batch should be processed. Yes
created_at integer (unixtime) The Unix timestamp (in seconds) for when the batch was created. Yes
endpoint string The OpenAI API endpoint used by the batch. Yes
error_file_id string The ID of the file containing the outputs of requests with errors. No
errors OpenAI.BatchErrors No
expired_at integer (unixtime) The Unix timestamp (in seconds) for when the batch expired. No
expires_at integer (unixtime) The Unix timestamp (in seconds) for when the batch will expire. No
failed_at integer (unixtime) The Unix timestamp (in seconds) for when the batch failed. No
finalizing_at integer (unixtime) The Unix timestamp (in seconds) for when the batch started finalizing. No
id string Yes
in_progress_at integer (unixtime) The Unix timestamp (in seconds) for when the batch started processing. No
input_file_id string or null No
metadata OpenAI.Metadata or null No
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.		 No
object enum The object type, which is always batch.
Possible values: batch		 Yes
output_file_id string The ID of the file containing the outputs of successfully executed requests. No
request_counts OpenAI.BatchRequestCounts No
└─ completed integer Yes
└─ failed integer Yes
└─ total integer Yes
status enum The current status of the batch.
Possible values: validating, failed, in_progress, finalizing, completed, expired, cancelling, cancelled		 Yes
usage OpenAI.BatchUsage No
└─ input_tokens integer Yes
└─ input_tokens_details OpenAI.BatchUsageInputTokensDetails Yes
└─ output_tokens integer Yes
└─ output_tokens_details OpenAI.BatchUsageOutputTokensDetails Yes
└─ total_tokens integer Yes

OpenAI.BatchError

Name Type Description Required Default
code string An error code identifying the error type. No
line integer or null The line number of the input file where the error occurred, if applicable. No
message string A human-readable message providing more details about the error. No
param string or null The name of the parameter that caused the error, if applicable. No

OpenAI.BatchErrors

Name Type Description Required Default
data array of OpenAI.BatchError No
object string No

OpenAI.BatchRequestCounts

Name Type Description Required Default
completed integer Yes
failed integer Yes
total integer Yes

OpenAI.BatchUsage

Name Type Description Required Default
input_tokens integer Yes
input_tokens_details OpenAI.BatchUsageInputTokensDetails Yes
output_tokens integer Yes
output_tokens_details OpenAI.BatchUsageOutputTokensDetails Yes
total_tokens integer Yes

OpenAI.BatchUsageInputTokensDetails

Name Type Description Required Default
cached_tokens integer Yes

OpenAI.BatchUsageOutputTokensDetails

Name Type Description Required Default
reasoning_tokens integer Yes

OpenAI.ListBatchesResponse

Name Type Description Required Default
data array of OpenAI.Batch Yes
first_id string No
has_more boolean Yes
last_id string No
object enum
Possible values: list		 Yes

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

Type: object

  • Last updated on