Core Concepts

Get Started: Running AI Task Builder Batches via Prolific’s API

View as MarkdownOpen in ClaudeOpen in ChatGPT

What you’ll accomplish

  • Upload raw datapoints (e.g., text, image URLs) into an AI Task Builder Dataset
  • Create an AI Task Builder Batch and attach Instructions
  • Convert your dataset into tasks and wait until the batch is READY
  • Create and publish a Prolific study that references the batch
  • Pull annotated responses from the batch

For detailed reference documentation, see:

Prerequisites

  • Your workspace_id
  • Your API token (Authorization: Token ...)
  • Decide how many tasks per participant you want to show (via tasks_per_group)
  • Decide your study settings (reward, sample size, timing, targeting)

Step-by-step guide

1

Create a Dataset

Create a container that will hold the datapoints participants will annotate.

POST
https://api.prolific.com/api/v1/data-collection/datasets
Body

Response will include id (your dataset_id) and status (one of UNINITIALISED|PROCESSING|READY|ERROR).

2

Request An Upload URL For Your Data

Upload one or more files (CSV format) that contain the datapoints.

GET
https://api.prolific.com/api/v1/data-collection/datasets/:dataset_id/upload-url/:filename
Path Parameters

The response body will be structured as follows

1{
2    "upload_url": "string",
3    "expires_at": "string",  // ISO-8601 DateTime string
4    "http_method": "string", // PUT in all instances
5    "dataset_id": "string"
6}
3

Upload Your Data (files → dataset)

Upload the file containing your datapoints.

$curl -X PUT "UPLOAD_URL_FROM_PREVIOUS_STEP" --data-binary "@{path_to_file}"

Poll status until the dataset is processed:

${"status": "READY"} # (wait for READY)

For advanced dataset options including metadata columns and custom task grouping, see Working with Datasets.

4

Create a Batch

Batches bind datasets + instructions into something you can attach to a Prolific study.

You can also include task details here with introductions and steps. task_introduction and task_steps fields support basic HTML.

POST
https://api.prolific.com/api/v1/data-collection/batches
Body

(Note: dataset_id is optional at creation time and can be added later via update, but must be provided before setup.)

Save the returned id as BATCH_ID.

1

Update a Batch (optional)

You can update a batch’s name, task details, or associated dataset after creation.

PATCH
https://api.prolific.com/api/v1/data-collection/batches/:batch_id
Path Parameters
Body

All fields are optional - include only what you want to update.

2

Duplicate a Batch (optional)

You can create a copy of an existing batch, either with or without its dataset.

Duplicate with the same dataset (dataset is shared, not copied)

$curl -X POST https://api.prolific.com/api/v1/data-collection/batches/BATCH_ID/duplicate \
>  -H "Authorization: Token YOUR_API_TOKEN" \
>  -H "Content-Type: application/json" \
>  -d '{
>    "name": "Copy of My Batch"
>  }'

Duplicate without a dataset (requires new upload)

$curl -X POST https://api.prolific.com/api/v1/data-collection/batches/BATCH_ID/duplicate \
>  -H "Authorization: Token YOUR_API_TOKEN" \
>  -H "Content-Type: application/json" \
>  -d '{
>    "name": "Copy of My Batch",
>    "upload_new_dataset": true
>  }'

If name is omitted, the duplicate will be named [Original Batch Name] (Copy).

Note: When duplicating with a dataset, both batches will reference the same dataset - it is not duplicated.

6

Add Instructions to the Batch

You can create multiple instructions. Types supported:

  • multiple_choice — selection from options (use answer_limit for single or multi-select)
  • free_text — open-ended text input
  • multiple_choice_with_free_text — selection with associated free text fields
  • file_upload — file submission

For full schema details, see Instructions.

POST
https://api.prolific.com/api/v1/data-collection/batches/:batch_id/instructions
Path Parameters

(You can later PUT the same endpoint to update instructions - please include the complete payload as it will replace all instructions on the batch, or GET it to read them back.)

7

Set Up the Batch (build tasks, set tasks per participant)

Configure how datapoints become tasks and how many tasks each participant gets.

POST
https://api.prolific.com/api/v1/data-collection/batches/:batch_id/setup
Path Parameters
Body

Note: The dataset must be in READY status before running the setup endpoint.

Now poll batch status until it’s READY:

GET
https://api.prolific.com/api/v1/data-collection/batches/:batch_id
Path Parameters
${"status":"READY"} # (possible values: UNINITIALISED|PROCESSING|READY|ERROR)
8

Create a Prolific Study that References the Batch

When the batch is READY, create a standard study but include these two fields:

  • "data_collection_method": "AI_TASK_BUILDER_BATCH"
  • "data_collection_id": "BATCH_ID"
POST
https://api.prolific.com/api/v1/studies/
Body
9

Publish the Study

POST
https://api.prolific.com/api/v1/studies/:id/transition/
Path Parameters
Body

(Other actions available include PAUSE, START (resume), and STOP.)

10

Retrieve Annotated Responses

There are two ways to retrieve responses once participants have completed their tasks.

Option 1: JSON responses

Get individual responses as JSON, useful for processing programmatically or streaming results as they come in.

GET
https://api.prolific.com/api/v1/data-collection/batches/:batch_id/responses
Path Parameters
1{
2  "results": [
3    {
4      "id": "01997d0c-34ab-748a-b6e3-104288f7a1bf",
5      "batch_id": "01997d05-8689-72a8-b980-3f930729f28a",
6      "participant_id": "6862a1a367ad476b8601fa2a",
7      "submission_id": "68d43c57a56e9439d5d1e93e",
8      "task_id": "84cc7c99-9097-5c0f-8052-65382273ace5",
9      "response": {
10        "instruction_id": "01997d05-8f20-734f-ad19-c82e279b5118",
11        "type": "free_text",
12        "answer": [
13          { "value": "abc" }
14        ]
15      },
16      "created_at": "2025-09-24T18:46:15.979Z"
17    }
18  ],
19  "meta": {
20    "count": 1
21  }
22}

Option 2: CSV report

Download a CSV report containing your original data with response columns appended.

GET
https://api.prolific.com/api/v1/data-collection/batches/:batch_id/report/
Path Parameters

This returns a presigned URL to download the CSV:

1{
2  "url": "https://...",
3  "expires_at": "2025-01-20T10:17:34.949Z",
4  "http_method": "GET"
5}

Use the url to download your annotated dataset.

Operational Notes & Tips

  • Statuses: Datasets and Batches both progress through UNINITIALISED → PROCESSING → READY (or ERROR). Don’t attach a batch to a study until it’s READY.
  • Instructions: You can mix multiple instruction types within the same batch (e.g., two multiple_choice plus one free_text).
  • tasks_per_group: Controls how many tasks a single participant receives in one “sitting” (this is what will be classed as a single Submission on Prolific). Increase to reduce study overhead and per-task price dispersion; decrease if tasks are long.
  • Targeting & Reward: As with any Prolific study, all participants share the same targeting and reward.
  • Once a batch has been set up (step 6) you can no longer edit its instructions.
  • Dataset Requirements: Datasets do not need to be in READY status when creating, updating, or duplicating batches. However, the dataset must be in READY status before running the setup endpoint.
  • Batch Duplication: When duplicating a batch with a dataset, the dataset is shared between both batches, not duplicated. If you need separate datasets, use upload_new_dataset: true.