Collecting original data with AI Task Builder Collections

Install and authenticate the Prolific CLI

The Prolific CLI lets you create collections, publish studies, and view submissions without writing API calls directly.

$
gh repo clone prolific-oss/cli prolific-cli
$
cd prolific-cli && make build
$
mkdir -p ~/.local/bin && cp prolific ~/.local/bin/
$
cd .. && rm -rf prolific-cli

Configure your API token by creating ~/.config/prolific-oss/prolific.yaml:

1
prolific_token: <your_api_token>

Verify authentication:

$
prolific whoami

Define your study

Create a JSON template for your study. When you publish via collection publish, the CLI automatically injects data_collection_method and data_collection_id; you don’t need to set these manually.

1
{
2
  "name": "My Study",
3
  "description": "<p>Participant-facing description of your study.</p>",
4
  "project": "<project_id>",
5
  "reward": 50,
6
  "estimated_completion_time": 5,
7
  "total_available_places": 100,
8
  "prolific_id_option": "question",
9
  "completion_codes": [
10
    {
11
      "code": "MYCODE1",
12
      "code_type": "COMPLETED",
13
      "actions": [{ "action": "AUTOMATICALLY_APPROVE" }]
14
    }
15
  ],
16
  "device_compatibility": ["mobile", "desktop", "tablet"],
17
  "peripheral_requirements": [],
18
  "filters": [],
19
  "submissions_config": {
20
    "max_submissions_per_participant": 1
21
  }
22
}

Reward and pricing:

• reward is in pence (GBP) or cents (USD)
• Prolific’s minimum rate is £6 / $8 per hour
• To calculate a reward that fits a total budget: reward_per_person = (budget / participants) / 1.4 (the 1.4 accounts for Prolific’s ~40% service fee on workspace-billed studies)

Participant targeting with filters:

You can restrict your study to participants matching specific criteria. For example, to target pet owners:

1
"filters": [
2
  {
3
    "filter_id": "pets",
4
    "selected_values": ["0", "1", "2", "3", "4", "5", "6", "7"]
5
  }
6
]

Browse available filters by querying the API:

$
curl -H "Authorization: Token <your_token>" https://api.prolific.com/api/v1/filters/

Define your collection

Create a YAML file describing your collection. A collection is made up of one or more pages (collection_items), each containing instructions and content blocks (page_items).

1
# collection.yaml
2
workspace_id: <your_workspace_id>
3
name: My Collection
4
description: A brief description of what participants will do.
5
task_details:
6
  task_name: Task title shown to participants
7
  task_introduction: "<p>Brief introduction shown before participants begin.</p>"
8
  task_steps: "<ol><li>Step one</li><li>Step two</li></ol>"
9
collection_items:
10
  - order: 0
11
    title: Page title
12
    page_items:
13
      - order: 0
14
        type: rich_text
15
        content: |
16
          Instructions shown to participants on this page.
17
        content_format: markdown  # optional; defaults to html
18
      - order: 1
19
        type: file_upload
20
        description: Upload your file here
21
        accepted_file_types:
22
          - .jpg
23
          - .jpeg
24
          - .png
25
        max_file_size_mb: 10.0
26
        min_file_count: 1
27
        max_file_count: 1

Supported page item types:

Instruction types collect participant input:

Content block types display content to participants (no input collected):

Once you’re happy with your collection definition, create it:

$
prolific collection create -t collection.yaml

Save the ID from the response; you’ll need it in the next step.

Create a draft study

Link your collection to a study and create it in draft status for review before going live:

$
prolific collection publish <collection_id> -t study-template.json --draft

The --draft flag creates the study as UNPUBLISHED so you can review and adjust it before participants can see it. Save the Study ID from the output.

To update any fields on the draft (e.g. adjust the reward):

$
echo '{"reward": 60}' | prolific study update <study_id> -t -

All fields can be updated on a draft study. Once published, only certain fields (such as total_available_places) can be changed.

Preview and publish the study

Before going live, preview your study to check how it will appear to participants:

$
prolific collection publish <collection_id> -t study-template.json --preview

This returns a preview URL you can open in your browser to walk through the participant experience.

When you’re ready to go live, transition the draft study to active:

$
prolific study transition <study_id> -a PUBLISH

Once successfully published, the study’s status will be ACTIVE and participants matching your filters will begin to see it.

Monitor submissions

View incoming submissions for your study:

$
prolific submission list -s <study_id>

This shows each submission’s participant ID, status, and time taken. Statuses include:

You can also view submissions in the app at: https://app.prolific.com/researcher/studies/<study_id>