Skip to navigation
API ReferenceAI Task Builder

Create a Batch

View as MarkdownOpen in Claude

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

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.

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

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.

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
Allowed values:
total_task_countinteger>=0
total_instruction_countinteger>=0
workspace_idstring
task_detailsobject
batch_itemslist of objects or nullOptional

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