---
title: "Queue a batch of up to 200 renders from a table"
method: POST
path: "/batch-tasks"
---

# Queue a batch of up to 200 renders from a table

`POST /batch-tasks`

## Request

- Base URL: `https://rendry.io/api/v1`
- URL: `https://rendry.io/api/v1/batch-tasks`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer
  - HTTP bearer

One template x a table of rows, rendered asynchronously. Use this instead of looping /render/batch when the set is bigger than 10: the quota is checked for the WHOLE batch up front, rows go through the shared render queue, and the result is one archive. Poll /batch-tasks/{id} for progress and fetch /batch-tasks/{id}/archive when it is done.

## Headers

- `X-Rendry-Account` string

## Request body

- object
  - `preset_id` string, required
  - `table` string, required: CSV or TSV with a header row; up to 200 data rows
  - `mapping` object: column -> template variable; omit to use the mapping from /batch-tasks/preview
  - `rows` object: Row sources for the WHOLE run — the arrays a repeat group or a table's rows_key consumes. A pasted cell is a string, so arrays travel here and not in the table; for a different basket per file, loop over render_image
  - `format` 'png' | 'jpeg' | 'webp'
  - `quality` integer
  - `max_width` integer

## Response `202`

Queued. The rows render in the background; poll status_url.

- BatchTaskAccepted: POST /batch-tasks queued the rows; poll status_url.
  - `task_id` string, required
  - `rows_total` integer, required: Data rows in the table
  - `enqueued` integer, required: Rows that reached the render queue; the rest are reported as failed rows in the status
  - `status_url` string, required: Path of GET /batch-tasks/{id}, relative to the API origin

## Other responses

- `400`: Refused before anything is charged. `error` is a machine code (batch_table_empty, batch_table_no_rows, batch_table_ragged_row, batch_too_many_rows, batch_table_too_big, batch_table_unparseable, batch_mapping_mismatch, batch_row_invalid, batch_output_invalid), its numbers ride beside it (row, rows, limit, cells, columns, unknown_columns, unknown_variables, variables, detail; a row whose variables do not resolve adds `diagnostics`), and `message` is the English sentence. `invalid_request` when the body is not a JSON object; `unknown_field` (with `fields`) for a key this door does not read — a near miss is renamed instead and reported in `autofixes`.
- `402`: Not enough credits for the whole batch
- `403`: API key scope does not allow rendering
- `503`: `service_unavailable`: the template could not be read, or `billing_unavailable`: the balance could not be checked (our side); retry. Nothing was created or charged.

---

[API](https://skmtc.dev/rendry/apis/rendry-api.md) · [All operations](https://skmtc.dev/rendry/apis/rendry-api/llms.txt) · [OpenAPI document](https://skmtc.dev/rendry/apis/rendry-api/revisions/c4fb572c26c9?raw)