API reference · Batches
Cancel a batch (requests in flight may finish; completed ones are kept and charged)
/v1/batches/{batch_id}/cancel- TypeScript
client.batches.cancel()- Python
client.batches.cancel()- CLI
hayonix batches cancel
No new request starts. The batch moves to cancelling, then to cancelled once its partial result files are written; requests never run are listed in the error file and not charged. Cancelling again returns the batch unchanged; a batch that has already ended answers 409 batch_not_cancellable.
Project API key (Authorization: Bearer sk_…), or a console session. Requires the batch:update permission (a key's scope, or a role that includes it).
Examples
The samples read API_KEY and API_BASE_URL from the environment (see Setup). Values are examples.
curl -sS -X POST "$API_BASE_URL/batches/bat_01jc5zq4m8k3v6x9t2w7r0b1e4/cancel" \
-H "Authorization: Bearer $API_KEY"Request
| Header | Required | Description |
|---|---|---|
Authorization | yes | Bearer and your API key. The key implies its project. |
X-Project-Id | session only | The project to act in, for console sessions. Requests with an API key leave it out. |
Path parameters
batch_idstringrequiredID of the batch
ID with prefix bat_
Response
200 Batch — The batch, cancelling
idstringrequiredUnique ID (`bat_…`)
ID with prefix bat_
objectstringrequiredAlways `batch`: the type of this object
One of
batchendpointstringrequiredThe route every request goes to, such as `/v1/chat/completions`
modelstring | nullrequiredThe model every request names, when they all name the same one
errorsobject | nullrequiredWhy the batch failed (input-file problems, a billing stop)
ShowHide 2 fields of
errorsobjectstringrequiredAlways `list`: the type of this object
One of
listdataarray of objectrequiredThe items
ShowHide 4 fields of
datacodestringrequiredMachine-readable code
messagestringrequiredOne sentence for people
paramstring | nullrequiredThe field the error is about; null when it is not about one field
lineinteger | nullrequired1-based line of the input file; null when not about one line
input_file_idstringrequiredID of the input file
ID with prefix file_
completion_windowstringrequiredTime allowed to run every request, counted from creation; requests not run by `expires_at` are reported as failed
statusstringrequiredvalidating → in_progress → finalizing → completed | expired | failed; cancelling → cancelled. `failed` before `in_progress` means the input file could not be run.
One of
validatingfailedin_progressfinalizingcompletedexpiredcancellingcancelledoutput_file_idstring | nullrequiredJSONL of the requests that succeeded (purpose `batch_output`)
error_file_idstring | nullrequiredJSONL of the requests that failed or were not run
created_atintegerrequiredUnix seconds (OpenAI shape)
in_progress_atinteger | nullrequiredUnix seconds (OpenAI shape)
expires_atinteger | nullrequiredUnix seconds (OpenAI shape)
finalizing_atinteger | nullrequiredUnix seconds (OpenAI shape)
completed_atinteger | nullrequiredUnix seconds (OpenAI shape)
failed_atinteger | nullrequiredUnix seconds (OpenAI shape)
expired_atinteger | nullrequiredUnix seconds (OpenAI shape)
cancelling_atinteger | nullrequiredUnix seconds (OpenAI shape)
cancelled_atinteger | nullrequiredUnix seconds (OpenAI shape)
request_countsobjectrequiredProgress, counted in requests (input lines)
ShowHide 3 fields of
request_countstotalintegerrequiredRequests in the input file; 0 until validation has finished
completedintegerrequiredRequests that succeeded
failedintegerrequiredRequests that were invalid or failed, plus, once the batch stops early, those never run
usageobjectrequiredTokens of the requests completed so far
ShowHide 5 fields of
usageinput_tokensintegerrequiredPrompt tokens over all completed requests
input_tokens_detailsobjectrequiredBreakdown of `input_tokens`
ShowHide 1 field of
input_tokens_detailscached_tokensintegerrequiredPrompt tokens served from the prompt cache
output_tokensintegerrequiredGenerated tokens over all completed requests
output_tokens_detailsobjectrequiredBreakdown of `output_tokens`
ShowHide 1 field of
output_tokens_detailsreasoning_tokensintegerrequiredAlways 0: reasoning tokens are not counted separately
total_tokensintegerrequired`input_tokens` plus `output_tokens`
metadataobject | nullrequiredYour own key/value labels, returned as given
project_idstringrequiredProject it belongs to
ID with prefix prj_
stop_reasonstring | nullrequiredWhy the batch stopped before running every request: cancelled, expired, insufficient_credit, spend_limit_reached, organization_suspended, api_key_revoked, billing_<reason>
costobjectrequiredWhat the batch has cost so far
ShowHide 2 fields of
costcurrencystringrequiredAlways `usd`
One of
USDchargedstringrequirednano-USD charged so far for completed requests, at batch prices
pattern ^-?[0-9]+$
timelineobjectrequiredThe same stage times as ISO 8601 timestamps; a stage not reached is null. `expires_at` is when the completion window ends.
ShowHide 9 fields of
timelinecreated_atstring (date-time)requiredWhen it was created (ISO 8601, UTC)
in_progress_atstring (date-time) | nullrequiredTime in progress (ISO 8601, UTC)
finalizing_atstring (date-time) | nullrequiredTime finalizing (ISO 8601, UTC)
completed_atstring (date-time) | nullrequiredWhen it completed (null until then) (ISO 8601, UTC)
failed_atstring (date-time) | nullrequiredTime failed (ISO 8601, UTC)
expired_atstring (date-time) | nullrequiredTime expired (ISO 8601, UTC)
cancelling_atstring (date-time) | nullrequiredTime cancelling (ISO 8601, UTC)
cancelled_atstring (date-time) | nullrequiredWhen it was cancelled (null unless it was) (ISO 8601, UTC)
expires_atstring (date-time)requiredWhen it expires (null: never) (ISO 8601, UTC)
Example response
{
"id": "bat_01jc5zq4m8k3v6x9t2w7r0b1e4",
"object": "batch",
"endpoint": "string",
"model": "string",
"errors": {
"object": "list",
"data": [
{
"code": "string",
"message": "string",
"param": "string",
"line": 1
}
]
},
"input_file_id": "file_01jc5zq4m8k3v6x9t2w7r0b1e4",
"completion_window": "string",
"status": "validating",
"output_file_id": "string",
"error_file_id": "string",
"created_at": 1,
"in_progress_at": 1,
"expires_at": 1,
"finalizing_at": 1,
"completed_at": 1,
"failed_at": 1,
"expired_at": 1,
"cancelling_at": 1,
"cancelled_at": 1,
"request_counts": {
"total": 1,
"completed": 1,
"failed": 1
},
"usage": {
"input_tokens": 1,
"input_tokens_details": {
"cached_tokens": 1
},
"output_tokens": 1,
"output_tokens_details": {
"reasoning_tokens": 1
},
"total_tokens": 1
},
"metadata": {},
"project_id": "prj_01jc5zq4m8k3v6x9t2w7r0b1e4",
"stop_reason": "string",
"cost": {
"currency": "USD",
"charged": "1500000000"
},
"timeline": {
"created_at": "2026-01-01T00:00:00.000Z",
"in_progress_at": "2026-01-01T00:00:00.000Z",
"finalizing_at": "2026-01-01T00:00:00.000Z",
"completed_at": "2026-01-01T00:00:00.000Z",
"failed_at": "2026-01-01T00:00:00.000Z",
"expired_at": "2026-01-01T00:00:00.000Z",
"cancelling_at": "2026-01-01T00:00:00.000Z",
"cancelled_at": "2026-01-01T00:00:00.000Z",
"expires_at": "2026-01-01T00:00:00.000Z"
}
}Errors
Errors use the standard envelope. What this operation can answer:
| Status | Type | When |
|---|---|---|
400 | invalid_request_error | A parameter or body field is missing or not allowed; param names it. |
401 | authentication_error | The key or session is missing, revoked or expired. |
403 | permission_error | The credential lacks the permission this needs, or the organization is suspended. |
404 | not_found_error | No such resource in this project (an ID from another project is answered the same way). |
409 | conflict_error | The resource's current state does not allow this. |
429 | rate_limit_error rate_limited | Too many requests; retry after retry-after seconds. |