POST/v1/batches

Batches

Async bulk processing at half the per-call price. Upload a JSONL of requests as a file (purpose=batch), submit it against one target endpoint, then poll the batch until it completes and download the output (and any error) file. Designed for large overnight jobs that do not need a synchronous response.

Request

HTTP: POST
URL: /v1/batches
Auth: api_key

Try it

# submit a batch of chat requests
curl https://api.fightclub.pro/v1/batches \
  -H "Authorization: Bearer $FC_API_KEY" -H "Content-Type: application/json" \
  -d '{"input_file_id":"file_abc","endpoint":"/v1/chat/completions","completion_window":"24h"}'
# => { "id":"batch_...", "status":"validating", "request_counts":{"total":0,...} }

# poll, then fetch results when completed
curl https://api.fightclub.pro/v1/batches/batch_xyz \
  -H "Authorization: Bearer $FC_API_KEY"
curl https://api.fightclub.pro/v1/files/file_out/content \
  -H "Authorization: Bearer $FC_API_KEY" -o results.jsonl

Example response

{
  "id": "batch_8Cc1",
  "object": "batch",
  "endpoint": "/v1/chat/completions",
  "status": "in_progress",
  "input_file_id": "file_in",
  "completion_window": "24h",
  "request_counts": { "total": 1000, "completed": 240, "failed": 0 },
  "created_at": 1782300000
}

A representative 200 body. Ids and timestamps are illustrative.

Body parameters

Name	Type	Default	Description
input_file_id*	string	—	Id of a file uploaded with purpose=batch. Each line is one request object.
endpoint*	string	—	The endpoint every line targets: /v1/chat/completions \| /v1/embeddings \| /v1/moderations.
completion_window	string	24h	Only 24h is supported in v1.
metadata	object	optional	Free-form JSON: up to 16 keys, <=4 KB serialized.

* required.

Query parameters

Name	Type	Default	Description
status	string	optional	On GET /v1/batches: filter the list by status.
limit	integer	20	Page size for the list endpoint.
after	string	optional	Cursor: the last batch id from the previous page.

Response fields

Name	Type	Description
id	string	Batch id (batch_*).
object	string	"batch".
endpoint	string	The target endpoint.
input_file_id	string	The submitted input file.
completion_window	string	"24h".
status	string	validating \| in_progress \| finalizing \| completed \| failed \| cancelling \| cancelled \| expired.
output_file_id	string \| null	Results file id, set when completed.
error_file_id	string \| null	Per-line errors file id, if any line failed.
request_counts	object	{ total, completed, failed }.
created_at	integer	Unix timestamp (plus in_progress_at, finalizing_at, completed_at, failed_at, expired_at, cancelled_at as they occur).
metadata	object	Your metadata.

Errors

401missing_tokenNo Authorization header was sent.
401invalid_auth_schemeThe scheme was neither Bearer nor Client.
401invalid_token_formatA Bearer token not prefixed ko_.
401invalid_tokenThe API key is unknown, revoked or expired.
403insufficient_scopeThe key is valid but lacks the required scope.
400missing_input_file_idinput_file_id is absent.
400invalid_endpointendpoint is not one of the three supported targets.
400invalid_completion_windowcompletion_window is not 24h.
400input_file_wrong_purposeThe input file was not uploaded with purpose=batch.
400metadata_too_largemetadata over 4 KB.
400metadata_too_many_keysmetadata has more than 16 keys.
404not_foundNo such batch (also cross-tenant).

See the full error reference.

Related routes

GET	/v1/batches	List batches (query: status, limit, after).
GET	/v1/batches/{id}	Retrieve one batch and poll its status.
POST	/v1/batches/{id}/cancel	Cancel a batch that is still validating or in progress.

Notes

·Flow: upload input (purpose=batch) -> POST /v1/batches -> poll GET /v1/batches/{id} until status=completed -> download output_file_id via /v1/files/{id}/content.
·Batch pricing is half the equivalent synchronous per-call price.
·Partial failures do not fail the batch: failed lines land in error_file_id and request_counts.failed.

Examples

batch-overnight-classifications →