# Instructions

# Instructions

Instructions define what participants are asked to do in AI Task Builder. The same instruction types are available for both Batches and Collections.

For usage details, see [Working with Batches](/api-reference/ai-task-builder/batches) or [Working with Collections](/api-reference/ai-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 | Yes      | Position of this instruction relative to others       |
| `helper_text`            | string  | No       | Additional guidance text displayed below the question |
| `placeholder_text_input` | string  | No       | Placeholder text displayed in the input field         |

## Instruction types

### 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                    | Yes      | 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.
</Note>

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

| Field         | Type    | Required | Description              |
| ------------- | ------- | -------- | ------------------------ |
| `type`        | string  | Yes      | `"free_text"`            |
| `description` | string  | Yes      | The question or prompt   |
| `order`       | integer | Yes      | Position in the sequence |

#### 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..."
}
```

***

### 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                    | Yes      | 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.
</Note>

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

| Field         | Type    | Required | Description                          |
| ------------- | ------- | -------- | ------------------------------------ |
| `type`        | string  | Yes      | `"file_upload"`                      |
| `description` | string  | Yes      | The prompt describing what to upload |
| `order`       | integer | Yes      | Position in the sequence             |

#### Example

```json
{
  "type": "file_upload",
  "description": "Upload a photo of the item",
  "order": 3
}
```