Files & Batches
Create Batch
Create a batch from an uploaded JSONL file.
Overview
Upload a JSONL file with purpose=batch, then use its ID as input_file_id. Completed batches return output and error file IDs.
Input file
The file is JSONL: one request per line, up to 50,000 lines and 200 MiB. For /v1/embeddings, the total number of inputs across all lines is also limited to 50,000. Each line needs:
custom_id: a string, unique in the file.method:POST.url: the same value as the batchendpoint.body: the request body, withmodel.
{"custom_id": "req-1", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "gpt-5.6-terra", "messages": [{"role": "user", "content": "Hello"}], "max_tokens": 100}}Notes
- Batch input files must use
purpose=batch. completion_windowis24h, the default and only value.metadatatakes up to 16 string pairs: keys up to 64 characters, values up to 512.output_expires_aftersets when the result files expire:anchoriscreated_atorcompleted_at, andsecondsis at most 30 days.- Output order may differ from input order. Match each result by
custom_id. - Streaming is not supported inside batch items.
- Supported item endpoints are
/v1/chat/completionsand/v1/embeddings./v1/responsesis not supported. - The estimated cost is reserved when the batch is created. A balance that is too low returns
402. - An invalid file returns
400withparamset toinput_file_id, and the message names the line.
Example
Request
curl -X POST "https://api.tokenlab.sh/v1/batches" \
-H "Authorization: Bearer sk-your-api-key" \
-H "Content-Type: application/json" \
-d '{
"input_file_id": "file_abc123",
"endpoint": "/v1/chat/completions",
"completion_window": "24h"
}'Batch prices may differ from synchronous requests. Check the final bill for the charge.
Response
{
"id": "batch_abc123",
"object": "batch",
"endpoint": "/v1/chat/completions",
"input_file_id": "file_abc123",
"completion_window": "24h",
"status": "validating",
"output_file_id": null,
"error_file_id": null,
"created_at": 1706000000
}Important fields
Authorization
BearerAuth API Key authentication. Create or manage API keys in Dashboard > API > API Keys.
In: header
Headers
Per-request Delivery policy. Overrides the API key and Workspace defaults. Auto tries TokenLab Verified first and may switch once to Official only before output, request acceptance, or persistent resource creation.
Value in
- "auto"
- "verified"
- "official"
Request Body
application/json
Response
application/json
application/json
application/json
application/json
application/json