Batches

OpenAI's Batch API at the API root, with HIPS's additions an OpenAI client ignores: windows longer than 24h, the hips object and signed webhooks. How to use it, the price and the limits are on Batch jobs; times on these routes are Unix seconds.

Note

Files and batches are built and not offered in production yet: every route on this page answers 404 route_not_available until they are switched on.

POST/v1/batchesnot offered

OpenAI's Batch API. Not offered in production yet: 404 route_not_available.

GET/v1/batches/{batch_id}not offered

The Batch object. Not offered in production yet.

POST/v1/batches/{batch_id}/cancelnot offered

Cancels a batch. Not offered in production yet.

GET/v1/batchesnot offered

The batches the credential reaches, newest first. Not offered in production yet.

Fig. 1, sheet 17API reference

Create

00000000000000000000000000000000000000001{"input_file_id": "file_...", "endpoint": "/v1/chat/completions", "completion_window": "72h", "metadata": {"run": "nightly-summaries"}}

Create sample

Parts list: POST /v1/batches

input_file_idRequired
A file of the workspace with purpose batch, within the credential's reach; unknown is a 404 file_not_found.
endpointRequired
/v1/chat/completions, the one endpoint a batch takes as built, equal to the file's url. Any other is a 400 unsupported_value.
completion_windowAccepted
A whole number of hours or days from 24h to 7d (24h, 36h, 3d, 7d), 24h when absent, one price for every window. Anything else is a 400 invalid_value.
metadataAccepted
OpenAI's: up to 16 pairs, keys up to 64 characters, values up to 512.
output_expires_afterAccepted
{"anchor": "created_at", "seconds"}, for the output and error files. 30 days by default.
RequirementsHeaders
x-hips-pool, x-hips-region and x-hips-fallback over the key's defaults set the requirements of every line, frozen on the batch. A batch is priced in market mode: x-hips-pricing-mode: stable is a 400 unsupported_value.

The gateway answers at once with the Batch object in validating, the quote bound; a model sold without batch is a 400 batch_not_offered, and a model the catalog does not know a 404 model_not_found. Takes idempotency-key.

Batch object

00000000000000000000000000000000000000001{2  "id": "batch_...",3  "object": "batch",4  "endpoint": "/v1/chat/completions",5  "model": "<pinned id>",6  "errors": null,7  "input_file_id": "file_...",8  "completion_window": "72h",9  "status": "in_progress",10  "output_file_id": null,11  "error_file_id": null,12  "created_at": 1792576800,13  "in_progress_at": 1792576860,14  "expires_at": 1792836000,15  "finalizing_at": null,16  "completed_at": null,17  "failed_at": null,18  "expired_at": null,19  "cancelling_at": null,20  "cancelled_at": null,21  "request_counts": {"total": 2, "completed": 1, "failed": 0},22  "usage": {"input_tokens": 0, "input_tokens_details": {"cached_tokens": 0}, "output_tokens": 0, "output_tokens_details": {"reasoning_tokens": 0}, "total_tokens": 0},23  "metadata": {"run": "nightly-summaries"},24  "hips": {"quote": "quote_...", "requirements": {"pool": "certified", "pricing_mode": "market", "region": null, "fallback": false}, "batch_discount_percent": 50, "max_charge_micros": 0, "held_micros": 0, "cost_micros": 0, "task_units": null, "request_counts": {"expired": 0, "cancelled": 0}}25}

Batch object sample

Parts list: The Batch object

model
The pinned id every line runs on: an id or alias in the lines resolves at creation and does not move during the window.
status
validating, failed, in_progress, finalizing, completed, expired, cancelling, cancelled, each with its time (Batch jobs says what each means).
request_counts
total, completed (lines answered 2xx) and failed (every line in the error file, expired and cancelled ones included).
usage
OpenAI's, summed over the finished lines.
errors
Set only in failed: {"object": "list", "data": [{"code", "message", "param", "line"}]}, the validation codes of Batch jobs.
hips
The bound quote, the frozen requirements, batch_discount_percent (50), max_charge_micros computed at validation, held_micros still held against the balance, cost_micros of the lines finished so far, task_units, and the expired and cancelled lines among failed.

Parts list: Cancel and list

POST /v1/batches/{batch_id}/cancel
No body. A batch in validating or in_progress enters cancelling; one already cancelling or ended answers unchanged. Takes idempotency-key.
GET /v1/batches
Newest first, after and limit; OpenAI's list with first_id, last_id and has_more. A full key lists the workspace's batches; an inference_only key and a person's token those they created.

Output and error lines

Line kind	Where	Shape
Answered 2xx	Output file	`id` (`batch_req_...`), `custom_id`, `response` with `status_code`, `request_id` and `body`, `error: null`
Answered with an error status	Error file	The same `response`, its `body` the error envelope; not charged
Never answered	Error file	`response: null`, `error` with `code` (`batch_expired`, `batch_cancelled`, `attempt_failed`) and `message`; not charged

Status	Type	Code	Situation	Retry
400	`invalid_request_error`	`missing_required_parameter`	A required field or header is absent; `param` names it	No
400	`invalid_request_error`	`invalid_value`	A value is out of range or malformed: `stop` with more than 16 entries, a `prompt_cache_key` over 512 characters, a string holding a lone surrogate escape, a router name with an empty or unknown suffix, both `max_tokens` names with different values	No
400	`invalid_request_error`	`unsupported_value`	`n` other than 1, `stream_options` without `stream`, a message role, part, item or tool type not accepted, a hosted tool that is not served	No
400	`invalid_request_error`	`file_too_large`, `invalid_file_format`, `batch_not_offered`	A batch input file over 200 MB; one that is not UTF-8 JSON Lines of objects, is empty, holds more than 50,000 lines, or names more than one model, one `url` or a router (the message names the first line at fault); a batch of a model sold without batch. Batches and files are not offered in production yet	No
403	`permission_error`	`guardrail_unsupported`	A content moderation guardrail applies to text it does not scan yet: a batch, or a task request with text; the guardrail named, uncharged	No
404	`not_found_error`	`model_not_found`	Unknown catalog id, alias, pinned id or `dep_`; another workspace's `dep_`; a name starting with `hips-router` that is not one of the four routers	No
404	`not_found_error`	`upload_not_found`, `file_not_found`, `batch_not_found`	An id in the path, or `input_file_id`, that is unknown, deleted, expired, another workspace's, or out of the credential's reach. Batches and files are not offered in production yet	No
404	`not_found_error`	`route_not_available`	A route that is built and not offered on this gateway: uploads, files and batches in production, and `POST /v1/messages/count_tokens`	No
429	`rate_limit_error`	`rate_limit_exceeded`	A rate limit; `param` is `requests`, `tokens`, `uploads`, `batches` (batches created per hour) or `knowledge_search`; `Retry-After`	Yes, after `Retry-After`
429	`rate_limit_error`	`concurrency_limit_exceeded`	Too many open batches; `param` is `batches`; `Retry-After`	Yes, after `Retry-After`

Status
400
Type
invalid_request_error
Code
missing_required_parameter
Situation
A required field or header is absent; param names it
Retry
No
Status
400
Type
invalid_request_error
Code
invalid_value
Situation
A value is out of range or malformed: stop with more than 16 entries, a prompt_cache_key over 512 characters, a string holding a lone surrogate escape, a router name with an empty or unknown suffix, both max_tokens names with different values
Retry
No
Status
400
Type
invalid_request_error
Code
unsupported_value
Situation
n other than 1, stream_options without stream, a message role, part, item or tool type not accepted, a hosted tool that is not served
Retry
No
Status
400
Type
invalid_request_error
Code
file_too_large, invalid_file_format, batch_not_offered
Situation
A batch input file over 200 MB; one that is not UTF-8 JSON Lines of objects, is empty, holds more than 50,000 lines, or names more than one model, one url or a router (the message names the first line at fault); a batch of a model sold without batch. Batches and files are not offered in production yet
Retry
No
Status
403
Type
permission_error
Code
guardrail_unsupported
Situation
A content moderation guardrail applies to text it does not scan yet: a batch, or a task request with text; the guardrail named, uncharged
Retry
No
Status
404
Type
not_found_error
Code
model_not_found
Situation
Unknown catalog id, alias, pinned id or dep_; another workspace's dep_; a name starting with hips-router that is not one of the four routers
Retry
No
Status
404
Type
not_found_error
Code
upload_not_found, file_not_found, batch_not_found
Situation
An id in the path, or input_file_id, that is unknown, deleted, expired, another workspace's, or out of the credential's reach. Batches and files are not offered in production yet
Retry
No
Status
404
Type
not_found_error
Code
route_not_available
Situation
A route that is built and not offered on this gateway: uploads, files and batches in production, and POST /v1/messages/count_tokens
Retry
No
Status
429
Type
rate_limit_error
Code
rate_limit_exceeded
Situation
A rate limit; param is requests, tokens, uploads, batches (batches created per hour) or knowledge_search; Retry-After
Retry
Yes, after Retry-After
Status
429
Type
rate_limit_error
Code
concurrency_limit_exceeded
Situation
Too many open batches; param is batches; Retry-After
Retry
Yes, after Retry-After

Sheet: 17 of 19
Detail: L
Updated: 2026-11-11

1{2 "id": "batch_...",3 "object": "batch",4 "endpoint": "/v1/chat/completions",5 "model": "<pinned id>",6 "errors": null,7 "input_file_id": "file_...",8 "completion_window": "72h",9 "status": "in_progress",10 "output_file_id": null,11 "error_file_id": null,12 "created_at": 1792576800,13 "in_progress_at": 1792576860,14 "expires_at": 1792836000,15 "finalizing_at": null,16 "completed_at": null,17 "failed_at": null,18 "expired_at": null,19 "cancelling_at": null,20 "cancelled_at": null,21 "request_counts": {"total": 2, "completed": 1, "failed": 0},22 "usage": {"input_tokens": 0, "input_tokens_details": {"cached_tokens": 0}, "output_tokens": 0, "output_tokens_details": {"reasoning_tokens": 0}, "total_tokens": 0},23 "metadata": {"run": "nightly-summaries"},24 "hips": {"quote": "quote_...", "requirements": {"pool": "certified", "pricing_mode": "market", "region": null, "fallback": false}, "batch_discount_percent": 50, "max_charge_micros": 0, "held_micros": 0, "cost_micros": 0, "task_units": null, "request_counts": {"expired": 0, "cancelled": 0}}25}

Line kind

Where

Shape

Answered 2xx

Output file

id (batch_req_...), custom_id, response with status_code, request_id and body, error: null

Answered with an error status

Error file

The same response, its body the error envelope; not charged

Never answered

Error file

response: null, error with code (batch_expired, batch_cancelled, attempt_failed) and message; not charged

Status

Type

Code

Situation

Retry

400

invalid_request_error

missing_required_parameter

A required field or header is absent; param names it

400

invalid_request_error

invalid_value

A value is out of range or malformed: stop with more than 16 entries, a prompt_cache_key over 512 characters, a string holding a lone surrogate escape, a router name with an empty or unknown suffix, both max_tokens names with different values

400

invalid_request_error

unsupported_value

n other than 1, stream_options without stream, a message role, part, item or tool type not accepted, a hosted tool that is not served

400

invalid_request_error

file_too_large, invalid_file_format, batch_not_offered

A batch input file over 200 MB; one that is not UTF-8 JSON Lines of objects, is empty, holds more than 50,000 lines, or names more than one model, one url or a router (the message names the first line at fault); a batch of a model sold without batch. Batches and files are not offered in production yet

403

permission_error

guardrail_unsupported

A content moderation guardrail applies to text it does not scan yet: a batch, or a task request with text; the guardrail named, uncharged

404

not_found_error

model_not_found

Unknown catalog id, alias, pinned id or dep_; another workspace's dep_; a name starting with hips-router that is not one of the four routers

404

not_found_error

upload_not_found, file_not_found, batch_not_found

An id in the path, or input_file_id, that is unknown, deleted, expired, another workspace's, or out of the credential's reach. Batches and files are not offered in production yet

404

not_found_error

route_not_available

A route that is built and not offered on this gateway: uploads, files and batches in production, and POST /v1/messages/count_tokens

429

rate_limit_error

rate_limit_exceeded

A rate limit; param is requests, tokens, uploads, batches (batches created per hour) or knowledge_search; Retry-After

Yes, after Retry-After

429

rate_limit_error

concurrency_limit_exceeded

Too many open batches; param is batches; Retry-After

Yes, after Retry-After

Related sheets

Related sheets