Create a Batch | Prolific API

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 or image_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.

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` or `image_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.

Authentication

AuthorizationToken

The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.

Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.

If your token is leaked, delete it and create a new one directly in the app.

In your requests add Authorization header with the value Token <your token>.

The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings. Your API token does not have an expiry date and carries full permission, so be sure to keep them secure. If your token is leaked, delete it and create a new one directly in the app. In your requests add `Authorization` header with the value `Token <your token>`.

Request

This endpoint expects an object.

namestringRequired

The name of the batch

workspace_idstringRequired

The ID of the Prolific workspace

task_detailsobjectRequired

Task metadata displayed to participants

dataset_idstringOptionalformat: "uuid"

The ID of the dataset to attach (optional at creation time)

batch_itemslist of objects or nullOptional

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.

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`.

Response

Created

idstringformat: "uuid"

created_atdatetime

An ISO-8601 formatted string representing the batch creation time, in UTC.

created_bystring

User ID of the Prolific user that created the resource.

datasetslist of objects

namestring

statusenum

total_task_countinteger>=0

total_instruction_countinteger>=0

workspace_idstring

task_detailsobject

batch_itemslist of objects or null

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.

Errors

4XX

Client Request Error

422

Unprocessable Entity Error

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`

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).

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

$	curl -X POST https://api.prolific.com/api/v1/data-collection/batches \
>	-H "Authorization: Token <token>" \
>	-H "Content-Type: application/json" \
>	-d '{
>	"name": "Sentiment Analysis Batch",
>	"workspace_id": "6278acb09062db3b35bcbeb0",
>	"task_details": {
>	"task_name": "Evaluate Product Reviews",
>	"task_introduction": "<p>In this task, you will analyze product reviews and categorize their sentiment.</p>",
>	"task_steps": "<ol><li>Read each review carefully</li><li>Select the appropriate sentiment</li><li>Provide a brief explanation</li></ol>"
>	},
>	"dataset_id": "1234acb09999db4b99bcded1"
>	}'

Configurable task layouts via batch_items

Authentication

Request

Response

Errors

Configurable task layouts via batch_items

Configurable task layouts via `batch_items`

Configurable task layouts via `batch_items`