TokenLab

Files & Batches

Create Batch

Create a batch from an uploaded JSONL file.

POST
/v1/batches

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 batch endpoint.
  • body: the request body, with model.
{"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_window is 24h, the default and only value.
  • metadata takes up to 16 string pairs: keys up to 64 characters, values up to 512.
  • output_expires_after sets when the result files expire: anchor is created_at or completed_at, and seconds is 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/completions and /v1/embeddings. /v1/responses is not supported.
  • The estimated cost is reserved when the batch is created. A balance that is too low returns 402.
  • An invalid file returns 400 with param set to input_file_id, and the message names the line.

Example

Request

cURL
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 example

Response

200 OK
{
  "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

idstring
Batch ID.
statusstring
Batch status.
output_file_idstring|null
Output file ID after completion.

Authorization

BearerAuth
AuthorizationBearer <token>

API Key authentication. Create or manage API keys in Dashboard > API > API Keys.

In: header

Headers

X-TokenLab-Delivery-Policy?string

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