Create a Batch

Create a new AI Task Builder batch. The dataset does not need to be in READY status at creation time.

Configurable task layouts via batch_items

You can configure a custom task layout using batch_items which also stores instructions and content as part of batch creation. It replaces the deprecated POST /api/v1/data-collection/batches/{batch_id}/instructions endpoint, which will reject requests on batches that were created with batch_items.

batch_items is a nested layout describing what is shown to participants:

• batch_items is an ordered array of pages. Each page is shown to participants as a single screen.
• Each page has an ordered array of rows.
• Each row has 1 or 2 columns rendered side-by-side.
• Each column has one or more items — a dataset field reference, a content block (image, rich_text), or an instruction (free_text, free_text_with_unit, multiple_choice, multiple_choice_with_free_text, file_upload).

Items are a discriminated union on type. Each dataset_field item references a field in the attached dataset by name — only fields with type text, image_url, or audio_url are permitted, and the same field may not be referenced more than once on the same page.

On a successful response, every item in batch_items is returned with a server-assigned id.

If batch_items fails server-side validation (for example: a dataset_field item used when no v4 dataset with a populated schema is attached, an unknown dataset_field, the same dataset_field referenced more than once on a page, an answer_limit larger than the number of options, or a default_unit that does not match the supplied unit_options), the request fails with 422 Unprocessable Entity and an INVALID_BATCH_ITEMS payload containing per-item page / row / column / item locations. See the BatchItemsValidationError schema for the full shape.