Create a batch

POST/v1/batches

Create a batch.

Compatible with OpenAI's create-batch endpoint: starts a batch job at the provider over the requests in an uploaded JSONL file. input_file_id may be the VectorAxis id (vxf-...) of a file uploaded with the same virtual key; it is replaced by the provider's file id. Returns the batch as the provider reports it, with input_file_id answered as your vxf-... id. With a virtual key, the batch belongs to that key: only it can list, read, cancel or download it.

Authenticate with a BYOK virtual key or with x-provider and x-api-key; a PLATFORM virtual key is a 400. OpenAI credentials only; any other provider is a 422. Without x-retry-count a failed call is retried up to 3 times on 429 and 5xx. The key's checks, the plan's limits and the organization's approved-provider policy (403) apply.

Authorization

AuthorizationBearer <slug>.<secret>
A virtual key's API key (vk-....<secret>), as Authorization: Bearer. What the OpenAI SDK sends from its api_key. Used by the inference endpoints.
orx-virtual-keyheader
A virtual key's API key in the x-virtual-key header, for clients that keep Authorization for something else.
orx-api-keyheader
Direct credentials: the provider's own API key in x-api-key, with the provider named in x-provider (for example openai). On /v1/messages a virtual key is accepted in x-api-key too, which is what the Claude SDK sends.

Headers

x-providerstring
With direct credentials: the provider x-api-key belongs to, for example openai or anthropic (case and dashes are normalised). Not used with a virtual key.
x-retry-countinteger<int32>
How many times to retry a failed provider call, 0 to 5. Without the header, chat completions, Claude Messages and prompt completions do not retry, and the other endpoints retry up to 3 times. Retries back off exponentially from 1 second and honour a numeric Retry-After. The number made is in the x-retry-count response header.
x-retry-status-codesstring
Comma-separated provider status codes to retry on. Default 429,500,502,503,504,529.

Request body application/json

the batch to create

input_file_idstringrequired
The file holding the requests, one JSON request per line (JSONL), uploaded with purpose batch: its VectorAxis id (vxf-..., for a file uploaded with the same virtual key) or the provider's file id.
endpointstringrequired
The endpoint every request is sent to, for example /v1/chat/completions, /v1/responses or /v1/embeddings.
completion_windowstringrequired
The time the batch has to complete. OpenAI supports 24h.
metadatamap<string, string>
Your own string key/value pairs to attach to the batch. Optional.

Responses

200application/json

idstring
The provider's batch id, for example batch_....
objectstring
Always batch.
endpointstring
The endpoint every request in the batch is sent to, for example /v1/chat/completions.
errorsobject
The errors with the batch as a whole.
Child attributes
- objectstring
  Always list.
- dataobject[]
  The errors.
  Child attributes
  - codestring
    The provider's error code.
  - messagestring
    A human-readable description of the error.
  - paramstring
    The parameter the error is about. Absent when it is not about a parameter.
  - lineinteger<int32>
    The line of the input file the error is on, from 1. Absent when it is not about a line.
input_file_idstring
The provider's id of the input file.
completion_windowstring
The time the batch has to complete, for example 24h.
statusenum<string>
The batch's state: validating (checking the input file), in_progress (running), finalizing (assembling the results), completed (done; output_file_id is set), failed (failed before running; see errors), expired (did not finish within completion_window), cancelling or cancelled.
One of "validating", "in_progress", "finalizing", "completed", "failed", "expired", "cancelling", "cancelled"
output_file_idstring
The provider's id of the file with the successful results. Absent until the batch has results.
error_file_idstring
The provider's id of the file with the failed requests' errors. Absent when there are none.
created_atinteger<int64>
When the batch was created, as a Unix timestamp in seconds.
in_progress_atinteger<int64>
When the batch started running, as a Unix timestamp in seconds. Absent until then.
expires_atinteger<int64>
When the batch expires, as a Unix timestamp in seconds.
finalizing_atinteger<int64>
When the batch started finalizing, as a Unix timestamp in seconds. Absent until then.
completed_atinteger<int64>
When the batch completed, as a Unix timestamp in seconds. Absent until then.
failed_atinteger<int64>
When the batch failed, as a Unix timestamp in seconds. Absent unless it failed.
expired_atinteger<int64>
When the batch expired, as a Unix timestamp in seconds. Absent unless it expired.
cancelling_atinteger<int64>
When cancellation started, as a Unix timestamp in seconds. Absent unless it was cancelled.
cancelled_atinteger<int64>
When the batch was cancelled, as a Unix timestamp in seconds. Absent unless it was cancelled.
request_countsobject
How many of the batch's requests have finished so far.
Child attributes
- totalinteger<int32>
  Requests in the batch.
- completedinteger<int32>
  Requests that completed successfully.
- failedinteger<int32>
  Requests that failed.
metadatamap<string, string>
The key/value pairs you attached when creating the batch. Absent when none were.

Request

curl -X POST "https://api.vectoraxis.ai/v1/batches" \
  -H "Authorization: Bearer $VECTORAXIS_VIRTUAL_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "input_file_id": "string",
  "endpoint": "string",
  "completion_window": "string"
}'

VectorAxis is built by GK Labs, a member of NVIDIA Inception.