Drex guides
Batches
Submit many System One requests at once and collect their answers later, at a discount. How to submit a batch, follow it, read its results, and what it costs.
A batch is a set of System One requests you don't need answered right away: labelling a backlog, scoring yesterday's tickets, re-running an evaluation. You submit up to 1,000 tasks in one call and get a batch id back. Drex runs the tasks when it has spare capacity and finishes them within the batch's window, by default 24 hours. Each task is billed like an on-demand request, with 50% off by default.
Submit a batch
Each task is a POST /v1/systemone body without model, plus a custom_id of yours:
curl https://console.nace.ai/v1/batches \
-H "Authorization: Bearer $NACE_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: tickets-2026-11-03" \
-d '{
"model": "drex-v2.0",
"tasks": [
{
"custom_id": "ticket-1",
"state": "My payout failed twice and payroll is tomorrow.",
"questions": { "urgent": { "type": "noul", "instructions": "Does the customer need help today?" } }
},
{
"custom_id": "ticket-2",
"state": "How do I change the logo on my invoices?",
"questions": { "urgent": { "type": "noul", "instructions": "Does the customer need help today?" } }
}
]
}'The answer is 202 with the batch:
{
"id": "batch_7e1f0c2a9b8d4e6f8a0b1c2d3e4f5a6b",
"object": "batch",
"status": "in_progress",
"model": "drex-v2.0",
"price_factor": 0.5,
"task_counts": { "total": 2, "queued": 2, "running": 0, "succeeded": 0, "errored": 0, "expired": 0, "cancelled": 0 },
"cost_usd": 0,
"metadata": null,
"created_at": "2026-11-03T10:00:00.000Z",
"expires_at": "2026-11-04T10:00:00.000Z",
"ended_at": null,
"cancel_requested_at": null,
"results_available": true
}| Field | Required | What it is |
|---|---|---|
tasks | yes | 1 to 1,000 tasks, each custom_id (1 to 64 letters, digits or _ . : -, unique in the batch), state and questions as in System One. The whole body is at most 4 MB. |
model | no | The model every task runs on, as in POST /v1/systemone. |
metadata | no | Up to 16 KB of your own, returned with the batch. |
Every task is checked when you submit: a task that is invalid or too long for the model refuses the whole batch with 422, naming the task, so a stored task can only fail on Drex's side. Batches take text only, not images. A retried Idempotency-Key with the same body returns the same batch.
Follow a batch
Poll GET /v1/batches/{id} every minute or so. status is in_progress while tasks are queued or running, cancelling after a cancel while running tasks finish, and ended once no task is queued or running. task_counts shows where the tasks are, and cost_usd what the succeeded ones were charged so far.
Tasks wait while Drex is busy with on-demand traffic and run as soon as there is room, so a batch can take minutes or hours. Tasks still queued when expires_at passes end expired.
GET /v1/batches lists your batches, newest first. POST /v1/batches/{id}/cancel ends the queued tasks as cancelled; tasks already running finish.
Read the results
GET /v1/batches/{id}/results returns the tasks in the order you sent them, 100 at a time by default (limit up to 1,000, then cursor with the next_cursor of the previous page; status keeps one status):
{
"items": [
{
"custom_id": "ticket-1",
"status": "succeeded",
"model": "drex-v2.0",
"answers": { "urgent": { "type": "noul", "noul": 0.94, "confidence": 0.94 } },
"usage": { "input_tokens": 61, "output_tokens": 1 },
"cost_usd": 0.0
},
{ "custom_id": "ticket-2", "status": "errored", "error": { "code": "insufficient_credit" } }
],
"next_cursor": null,
"results_available": true
}answers are what POST /v1/systemone would have answered. An errored task's error.code says why: insufficient_credit or payment_required when the account could not pay for it when it ran, timeout, overloaded or unavailable after three tries, and too_long, invalid_request, model_unavailable or worker_lost otherwise.
Results are kept for 29 days after the batch ends, then cleared: results_available turns false and the answers are no longer returned.
What a batch costs
Each succeeded task is billed once, for its input tokens at the batch's price_factor of the model's on-demand price (see pricing), and appears in your usage like any request. The factor is fixed when you submit: 50% off unless your deployment says otherwise in price_factor. Tasks that error, expire or are cancelled are free.
Your available funds must cover the batch's worst-case cost when you submit it (402 otherwise), but nothing is set aside: each task reserves its own funds when it runs. If your balance runs out meanwhile, the remaining tasks end errored with insufficient_credit and are not charged.
Data
A task's state and questions are kept until it ends, then cleared; its answers are kept for 29 days after the batch ends. Deleting your account cancels your open batches and clears their content. Accounts with zero retention cannot submit batches (422, code zero_retention_unsupported).