DigitalOcean API (unofficial showcase)
POST/v1/batches

Create a Batch Inference Job

Submits a batch job against a previously uploaded JSONL input file. The upload must have completed before this call; otherwise the request is rejected.

Supply a unique request_id to make the submission idempotent — retries with the same value return the existing job. When provider is openai, the url on each JSONL line must match endpoint.

  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

6 body fields
file_idstringrequired
The `file_id` returned by `POST /v1/batches/files`.
providerstringrequired
The inference provider whose JSONL schema the input file conforms to. `openai` follows the OpenAI Batch API input schema (`custom_id`, `method`, `url`, `body`); `anthropic` follows the Anthropic Message Batches JSONL conventions.
Allowed:openaianthropic
endpointstringoptional
Inference endpoint each request is dispatched to. **Required when `provider` is `openai` and must match the `url` on every JSONL line. Must be omitted when `provider` is `anthropic`.**
Allowed:/v1/responses/v1/chat/completions
completion_windowstringrequired
Time window in which the job must complete. Jobs that do not finish in time transition to `expired`.
Allowed:24hDefault:24h
request_idstringrequired
Client-supplied idempotency key. Retries with the same value return the existing job instead of creating a duplicate.
metadataobjectoptional
Optional string-valued metadata to attach to the job.

10 status codes
201Batch job accepted. Poll `GET /v1/batches/{batch_id}` for status.
batch_idstringrequired
Unique identifier for the batch job.
statusstringrequired
Lifecycle status. Terminal states: `completed`, `failed`, `expired`, `cancelled`.
Allowed:validatingin_progressfinalizingcompletedfailedexpiredcancellingcancelled
providerstringrequired
Allowed:openaianthropic
endpointstringoptional
Inference endpoint each request is dispatched to.
completion_windowstringrequired
Allowed:24h
input_file_idstringrequired
The uploaded JSONL input file.
output_file_idstringoptional
Output JSONL file. Populated once the job completes.
error_file_idstringoptional
Error sidecar file. Null when no errors were produced.
request_countsobjectoptional
Aggregate request counts.
request_idstringoptional
The idempotency key supplied at creation.
metadataobjectoptional
Metadata attached at creation.
errorsarray<object>optional
Top-level errors that prevented the batch from completing.
created_atstringrequired
in_progress_atstringoptional
finalizing_atstringoptional
completed_atstringoptional
expires_atstringoptional
Derived from `created_at` plus `completion_window`.
cancelled_atstringoptional
failed_atstringoptional
400There was an error parsing the request body.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
401Authentication failed due to invalid credentials.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
403The authenticated principal does not have permission to perform this action on the requested resource.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
404The resource was not found.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
409The request could not be completed due to a conflict.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
422Unprocessable Entity
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
429The API rate limit has been exceeded.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
500There was a server error.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
defaultThere was an unexpected error.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Error handling

A 400 is returned: There was an error parsing the request body. A 401 is returned: Authentication failed due to invalid credentials. A 403 is returned: The authenticated principal does not have permission to perform this action on the requested resource. A 404 is returned: The resource was not found. A 409 is returned: The request could not be completed due to a conflict. A 422 is returned: Unprocessable Entity. A 429 is returned: The API rate limit has been exceeded. A 500 is returned: There was a server error. Any other status is an error: There was an unexpected error.