> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.prolific.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.prolific.com/_mcp/server. # Instructions Instructions define what participants are asked to do in 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](/api-reference/task-builder/batches) or [Working with Collections](/api-reference/task-builder/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 | > **Note** > > 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 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 | > **Note** > > 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 ```json { "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 ```json { "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 ```json { "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 ```json { "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 ```json { "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 ```json { "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 | > **Note** > > 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 ```json { "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` | > **Note** > > **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 ```json { "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 ```json { "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 ```json { "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 ```json { "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 ```json { "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