--- title: "Create a Batch" method: POST path: "/api/v1/data-collection/batches" tags: ["aiTaskBuilder"] --- # Create a Batch `POST /api/v1/data-collection/batches` 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`, `audio_url`, or `video_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. ## Headers - `Authorization` string, required ## Request body - object - `name` string, required — The name of the batch - `workspace_id` string, required — The ID of the Prolific workspace - `dataset_id` string, uuid — The ID of the dataset to attach (optional at creation time) - `task_details` ApiV1DataCollectionBatchesPostRequestBodyContentApplicationJsonSchemaTaskDetails, required — Task metadata displayed to participants - `task_name` string, required — The title displayed to participants - `task_introduction` string, required — HTML formatted introduction shown at the start of the task - `task_steps` string, required — HTML formatted step-by-step instructions - `batch_items` BatchItemsPage[], nullable — Inline pages of instructions and content shown to participants. Each entry is a page containing rows of columns of items (dataset field references, content blocks, or instructions). When supplied, this is the recommended way to author instructions — the legacy `POST /batches/{batch_id}/instructions` endpoint is rejected for batches created with `batch_items`. - `id` string — Server-assigned identifier; present on responses. Include to preserve an existing page when updating. - `display_position` 'intro' | 'outro' | 'body' — Renders the page once — before ("intro") or after ("outro") the repeating body — instead of once per datapoint. Omit (or set "body") for the default repeating behaviour. Pages with display_position "intro" or "outro" may only contain rich_text/image content blocks, not instructions or dataset_field refs. - `rows` BatchItemsRow[], required - `id` string — Server-assigned identifier; present on responses. Include to preserve an existing row when updating. - `columns` BatchItemsColumn[], required - `id` string — Server-assigned identifier; present on responses. Include to preserve an existing column when updating. - `items` BatchItemsItem[], required - union — A single item within a column. One of: a dataset field reference (`dataset_field`), a content block (`image`, `rich_text`), or an instruction (`free_text`, `free_text_with_unit`, `multiple_choice`, `multiple_choice_with_free_text`, `file_upload`). Discriminated on `type`. - object — References a field in the batch's attached dataset. At task time, the dataset value for the current datapoint is rendered at this position. Only dataset schema fields of type `text`, `image_url`, `audio_url`, or `video_url` are permitted, and the same field may not be referenced more than once on the same page. - … - object — An image content block rendered inline within the batch layout. - … - object — A rich-text content block rendered inline within the batch layout. - … - object — Free-text input instruction. - … - object — Free-text input instruction paired with a unit selector. - … - object — Multiple-choice instruction. - … - object — Multiple-choice instruction with an additional free-text input per selected option. - … - object — File upload instruction. - … ## Response `201` Created - AITaskBuilderBatchCreate - `id` string, uuid, required - `created_at` string, date-time, required — An ISO-8601 formatted string representing the batch creation time, in UTC. - `created_by` string, required — User ID of the Prolific user that created the resource. - `datasets` AiTaskBuilderBatchCreateDatasetsItems[], required - `id` string, uuid, required - `total_datapoint_count` integer, required - `name` string, required - `status` 'UNINITIALISED' | 'PROCESSING' | 'READY' | 'ERROR', required - `total_task_count` integer, required - `total_instruction_count` integer, required - `workspace_id` string, required - `task_details` AiTaskBuilderBatchCreateTaskDetails, required - `task_name` string, required - `task_introduction` string, required — HTML formatted task introduction - `task_steps` string, required — HTML formatted task steps - `batch_items` BatchItemsPage[], nullable — The persisted `batch_items` layout, returned only when `batch_items` was supplied on create. Every page, row, column, and item is returned with a server-assigned `id`. - `id` string — Server-assigned identifier; present on responses. Include to preserve an existing page when updating. - `display_position` 'intro' | 'outro' | 'body' — Renders the page once — before ("intro") or after ("outro") the repeating body — instead of once per datapoint. Omit (or set "body") for the default repeating behaviour. Pages with display_position "intro" or "outro" may only contain rich_text/image content blocks, not instructions or dataset_field refs. - `rows` BatchItemsRow[], required - `id` string — Server-assigned identifier; present on responses. Include to preserve an existing row when updating. - `columns` BatchItemsColumn[], required - `id` string — Server-assigned identifier; present on responses. Include to preserve an existing column when updating. - `items` BatchItemsItem[], required - union — A single item within a column. One of: a dataset field reference (`dataset_field`), a content block (`image`, `rich_text`), or an instruction (`free_text`, `free_text_with_unit`, `multiple_choice`, `multiple_choice_with_free_text`, `file_upload`). Discriminated on `type`. - object — References a field in the batch's attached dataset. At task time, the dataset value for the current datapoint is rendered at this position. Only dataset schema fields of type `text`, `image_url`, `audio_url`, or `video_url` are permitted, and the same field may not be referenced more than once on the same page. - … - object — An image content block rendered inline within the batch layout. - … - object — A rich-text content block rendered inline within the batch layout. - … - object — Free-text input instruction. - … - object — Free-text input instruction paired with a unit selector. - … - object — Multiple-choice instruction. - … - object — Multiple-choice instruction with an additional free-text input per selected option. - … - object — File upload instruction. - … ## Other responses - `400` — Error - `422` — Unprocessable Entity — `batch_items` failed validation --- [API](https://skmtc.net/prolific/apis/api-reference.md) · [All operations](https://skmtc.net/prolific/apis/api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/prolific/api-reference/versions/dc6f073a9827/schema)