Instructions | Prolific API

Instructions define what participants are asked to do in AI Task Builder. Most instruction types are available for both Batches and Collections. video_narration is available only in Batch layouts.

For usage details, see Working with Batches or Working with Collections.

Common fields

All instructions share these fields:

Field	Type	Required	Description
`type`	string	Yes	The instruction type
`description`	string	Yes	The prompt or question displayed to participants
`order`	integer	Collections only	Required for Collection instructions. Batch layouts use the item’s position in `batch_items`; the legacy Batch endpoint uses the order of the `instructions` array.
`helper_text`	string	No	Additional guidance text displayed below the question
`placeholder_text_input`	string	No	Placeholder text displayed in the input field

For Batch layouts created with batch_items, do not provide order on instructions. Their display order is defined by their position in the layout. The legacy Batch instructions endpoint is deprecated and preserves the order of its instructions array.

Instruction types

AI Task Builder supports the following instruction types:

multiple_choice - Selection from a list of options
free_text - Open-ended text input
free_text_with_unit - Text input with unit selection (e.g., measurements, currency)
multiple_choice_with_free_text - Selection with associated free text fields
file_upload - File submission field
video_narration - Spoken narration recorded while the participant watches a video (Batches only)

multiple_choice

A selection from a list of options. Use answer_limit to control single or multi-select behavior.

Field	Type	Required	Description
`type`	string	Yes	`"multiple_choice"`
`description`	string	Yes	The question or prompt
`order`	integer	Collections only	Position in the sequence
`answer_limit`	integer	Yes	Number of options that can be selected. Use `1` for single-select, `-1` for unlimited, or any number up to the total options.
`disable_dropdown`	boolean	No	When `true`, always renders checkbox/radio elements instead of a dropdown. Default: `false`
`options`	array	Yes	List of options (minimum 1)
`options[].label`	string	Yes	Display text shown to participants
`options[].value`	string, number, or boolean	Yes	Value returned in responses

By default, when there are 5 or more options, a dropdown select element is rendered instead of checkboxes or radio buttons. Set disable_dropdown: true to always use checkboxes (for multi-select) or radio buttons (for single-select) regardless of option count.

Example

{
  "type": "multiple_choice",
  "description": "What is the sentiment of this text?",
  "order": 1,
  "answer_limit": 1,
  "options": [
    { "label": "Positive", "value": "positive" },
    { "label": "Neutral", "value": "neutral" },
    { "label": "Negative", "value": "negative" }
  ]
}

Multi-select example

{
  "type": "multiple_choice",
  "description": "Select all topics that apply:",
  "order": 1,
  "answer_limit": -1,
  "options": [
    { "label": "Product quality", "value": "quality" },
    { "label": "Customer service", "value": "service" },
    { "label": "Pricing", "value": "pricing" },
    { "label": "Shipping", "value": "shipping" }
  ]
}

free_text

An open-ended text input field. Optionally includes validation constraints for the input value.

Field	Type	Required	Description
`type`	string	Yes	`"free_text"`
`description`	string	Yes	The question or prompt
`order`	integer	Collections only	Position in the sequence
`validation`	object	No	Optional validation constraints for the input value
`validation.type`	string	Yes (if `validation` provided)	The expected input type. `"number"` validates numeric input and min/max constrain the value. `"string"` validates text input and min/max constrain the character count
`validation.min`	number \| null	No	Minimum value or character count. `null` means unbounded below
`validation.max`	number \| null	No	Maximum value or character count. `null` means unbounded above

Example

{
  "type": "free_text",
  "description": "Explain your reasoning for the rating above",
  "order": 2,
  "helper_text": "Be specific about what influenced your decision",
  "placeholder_text_input": "e.g. The text contains positive language such as..."
}

Example with validation

{
  "type": "free_text",
  "description": "How old are you?",
  "order": 2,
  "validation": {
    "type": "number",
    "min": 18,
    "max": 120
  }
}

free_text_with_unit

A text input field where participants provide a numeric or text value along with a unit selection (e.g., measurements in cm or inches, weights in kg or lbs). The unit selector can appear before (prefix) or after (suffix) the text input.

Field	Type	Required	Description
`type`	string	Yes	`"free_text_with_unit"`
`description`	string	Yes	The question or prompt
`order`	integer	Collections only	Position in the sequence
`unit_options`	array	Yes	List of available units (minimum 2)
`unit_options[].label`	string	Yes	Display text shown to participants
`unit_options[].value`	string, number, or boolean	Yes	Value returned in responses
`unit_options[].validation`	object	No	Optional validation constraints for this unit option
`unit_options[].validation.type`	string	Yes (if `validation` provided)	The expected input type. `"number"` validates numeric input and min/max constrain the value. `"string"` validates text input and min/max constrain the character count
`unit_options[].validation.min`	number \| null	No	Minimum value or character count. `null` means unbounded below
`unit_options[].validation.max`	number \| null	No	Maximum value or character count. `null` means unbounded above
`unit_position`	string	Yes	Position of unit selector: `"prefix"` (before input) or `"suffix"` (after input)
`default_unit`	string	No	Default selected unit (must match a value from `unit_options`)

Example: Height measurement with validation

{
  "type": "free_text_with_unit",
  "description": "What is your height?",
  "order": 1,
  "unit_options": [
    {
      "label": "Centimeters",
      "value": "cm",
      "validation": { "type": "number", "min": 50, "max": 300 }
    },
    {
      "label": "Inches",
      "value": "in",
      "validation": { "type": "number", "min": 20, "max": 108 }
    }
  ],
  "unit_position": "suffix",
  "default_unit": "cm",
  "placeholder_text_input": "Enter your height"
}

Example: Currency amount

{
  "type": "free_text_with_unit",
  "description": "What is your budget?",
  "order": 1,
  "unit_options": [
    { "label": "$", "value": "usd" },
    { "label": "£", "value": "gbp" },
    { "label": "€", "value": "eur" }
  ],
  "unit_position": "prefix",
  "default_unit": "usd",
  "helper_text": "Enter the amount in your preferred currency"
}

multiple_choice_with_free_text

A selection from options, where each option has a heading and an associated free text field. Use this when you need participants to both select an option and provide additional context.

Field	Type	Required	Description
`type`	string	Yes	`"multiple_choice_with_free_text"`
`description`	string	Yes	The question or prompt
`order`	integer	Collections only	Position in the sequence
`answer_limit`	integer	Yes	Number of options that can be selected. Use `1` for single-select, `-1` for unlimited, or any number up to the total options.
`disable_dropdown`	boolean	No	When `true`, always renders checkbox/radio elements instead of a dropdown. Default: `false`
`options`	array	Yes	List of options (minimum 1)
`options[].label`	string	Yes	Display text shown to participants
`options[].value`	string, number, or boolean	Yes	Value returned in responses
`options[].heading`	string	Yes	Section heading that groups this option

Example

{
  "type": "multiple_choice_with_free_text",
  "description": "Rate the following aspects and provide comments:",
  "order": 1,
  "answer_limit": -1,
  "options": [
    { "label": "Good", "value": "accuracy_good", "heading": "Accuracy" },
    { "label": "Needs improvement", "value": "accuracy_poor", "heading": "Accuracy" },
    { "label": "Good", "value": "clarity_good", "heading": "Clarity" },
    { "label": "Needs improvement", "value": "clarity_poor", "heading": "Clarity" }
  ]
}

In this example, options are grouped under “Accuracy” and “Clarity” headings. Each selection includes an associated free text field for the participant to elaborate.

file_upload

A file submission field for participants to upload images, documents, or other files. Useful for collecting photos, documents, screenshots, or any file-based data from participants.

Field	Type	Required	Description
`type`	string	Yes	`"file_upload"`
`description`	string	Yes	The prompt describing what to upload
`order`	integer	Collections only	Position in the sequence
`accepted_file_types`	array of strings	No	File extensions to accept (e.g., `[".jpg", ".png", ".pdf"]`). Each extension must start with a dot. Minimum 1 extension if provided. Default: `[".jpg", ".jpeg", ".png", ".heic", ".heif"]`
`max_file_size_mb`	number	No	Maximum file size in megabytes per file. Must be a positive number. Default: `25`
`min_file_count`	integer	No	Minimum number of files required. Must be at least `1`. Default: `1`
`max_file_count`	integer	No	Maximum number of files allowed. Must be at least `1` and greater than or equal to `min_file_count`. Default: `10`

Validation rules:

All file type extensions must start with a dot (e.g., ".pdf", not "pdf")
max_file_size_mb must be a positive number
min_file_count must be at least 1
max_file_count must be greater than or equal to min_file_count
If you omit accepted_file_types, the instruction will only accept common image formats (JPG, PNG, HEIC, HEIF)

Example: Single image upload

{
  "type": "file_upload",
  "description": "Upload a clear photo of your receipt",
  "order": 1,
  "helper_text": "Make sure the receipt is fully visible and in focus",
  "accepted_file_types": [".jpg", ".jpeg", ".png"],
  "max_file_size_mb": 10,
  "min_file_count": 1,
  "max_file_count": 1
}

Example: Multiple document upload

{
  "type": "file_upload",
  "description": "Upload supporting documents",
  "order": 2,
  "helper_text": "You can upload between 2-5 documents in PDF or image format",
  "accepted_file_types": [".pdf", ".jpg", ".jpeg", ".png"],
  "max_file_size_mb": 25,
  "min_file_count": 2,
  "max_file_count": 5
}

Example: Flexible image collection

{
  "type": "file_upload",
  "description": "Upload photos of the product from different angles",
  "order": 3,
  "accepted_file_types": [".jpg", ".jpeg", ".png", ".heic", ".heif"],
  "max_file_size_mb": 15,
  "min_file_count": 3,
  "max_file_count": 10
}

video_narration

A Batch-only instruction that records a participant’s spoken narration while they watch a video. Place it alongside a video_url dataset field in a batch_items layout.

Field	Type	Required	Description
`type`	string	Yes	`"video_narration"`
`description`	string	Yes	The prompt displayed to the participant
`helper_text`	string	No	Additional guidance displayed below the prompt
`optional`	boolean	No	Whether the participant may skip the instruction. Default: `false`
`max_file_size_mb`	number	No	Maximum size of each recorded narration file in megabytes. Must be positive. Default: `50`
`narration_mode`	string	No	`"continuous"` records one narration spanning the video. `"segmented"` allows one or more narrations for video time ranges. Default: `"continuous"`

Example: Continuous narration

{
  "type": "video_narration",
  "description": "Describe what you see as the video plays.",
  "helper_text": "Speak clearly and narrate the full video.",
  "narration_mode": "continuous",
  "max_file_size_mb": 50
}

Example: Segmented narration

{
  "type": "video_narration",
  "description": "Narrate the notable events in this video.",
  "helper_text": "Create a separate narration for each relevant part of the video.",
  "narration_mode": "segmented"
}

Responses contain one recorded file for continuous narration, or one or more recorded files for segmented narration. Batch exports include the files in the archive’s files/ directory.

Validation

The optional validation object can be added to free_text instructions (top-level) and to individual unit_options items in free_text_with_unit instructions. It allows researchers to set min/max bounds on participant input.

Validation fields

Field	Type	Required	Description
`type`	string	Yes	`"number"` or `"string"`
`min`	number \| null	No	Minimum bound. `null` or omitted means unbounded below
`max`	number \| null	No	Maximum bound. `null` or omitted means unbounded above

Validation types

"number" — The input must be numeric. min and max constrain the numeric value. Use this for measurements, ages, quantities, etc.
"string" — The input is treated as text. min and max constrain the character count. Use this to enforce minimum or maximum text lengths.

Constraints

When both min and max are provided, min must be less than or equal to max
For type: "string", min and max must be non-negative integers
Setting min or max to null (or omitting it) means that direction is unbounded