Use these best practices to format a Word document, Google Doc, or questionnaire for AI programming in the MX8 Labs Research Platform. State question types, response lists, and logic explicitly so the platform can program the survey as intended.
The examples show how to write those instructions. Each is a reusable fragment: replace the question text and options, then update question numbers and references to match your questionnaire.
The blocks contain instructions for AI programming. For Python implementations and parameter definitions, follow the linked platform references. Read Survey logic best practices for the general conventions and Creating a new survey for the paste workflow.
How to write each question
- Put the question identifier and text first, then state the question type on its own line.
- Label response options, grid rows, and grid columns explicitly.
- Reference options by their exact wording, such as "Nike", and identify the source question in every rule.
- Put termination, show, skip, randomization, and validation rules on separate lines.
- Give every question with a termination rule a qualifying simulation default. Defaults affect test data only; see Setting test data defaults.
- Express instructions in plain text. Color and highlighting do not carry survey logic.
Single-select and termination
State fixed options by their full response text. This example randomizes the brand list, keeps "Other (please specify)" at the bottom, and screens out respondents immediately after Q3 unless they selected "Nike".
Q3. Which of the following brands have you purchased most recently?
Type: Single-Select
Response Options:
- Nike
- Adidas
- Converse
- New Balance
- Other (please specify)
randomize = True
Fixed Options = Other (please specify)
If Q3 is NOT "Nike", Terminate immediately after Q3
default = "Nike"
To terminate after a whole screener instead, place the termination rules after its final question and state where they run, for example: After Q5, terminate if Q3 is NOT "Nike". Include a qualifying default on each question used by those rules.
See Select Question and Terminating respondents.
Display styles
The question type determines how respondents answer; style controls its presentation. For example, add style = list to a single-select question to request a list presentation.
| Question type | Styles |
|---|---|
| Single-select | default, button, list, dropdown |
| Multi-select | default, button, list, dropdown |
| Ranking | default, button, list |
| Grid Select | button, radio |
| Multi-Select Grid | button, checkbox |
| Rating and Grid Rating | slider, button, star |
| Net Promoter Score | slider, button, star |
Use the linked references to check scale limits and how each style appears in the traditional and chat experiences.
Multi-select
Specify how many options respondents may select and which options are exclusive. "None of the above" cannot be selected together with another answer.
Q4. Which streaming services do you currently subscribe to? Select up to three.
Type: Multi-Select
Response Options:
- Netflix
- Hulu
- Disney+
- Max
- Peacock
- Other (please specify)
- None of the above
randomize = True
Fixed Options = Other (please specify), None of the above
Exclusive Options = None of the above
Min options = 1
Max options = 3
If "None of the above" at Q4, Skip to Q10
Branching
Name the source question, response, and destination on each line. Ensure Q6 and Q10 exist in the questionnaire that uses this fragment.
Q5. Do you currently subscribe to any streaming services?
Type: Single-Select
Response Options:
- Yes
- No
If Q5 = "Yes", Show Q6
If Q5 = "No", Skip to Q10
Numeric open ends and recodes
State the permitted numeric range, the screening condition, and the reporting categories separately. Use non-overlapping age bands with matching labels.
Q1. How old are you?
Type: Open-End (Numeric)
Allowed range = 0-100
If Q1 < 18, Terminate immediately after Q1
default = 34
Recode Q1 for reporting:
- 18-24 as "18-24"
- 25-44 as "25-44"
- 45-54 as "45-54"
- 55-100 as "55+"
See Number Question for numeric ranges and recodes.
Quotas
Place quota instructions after the relevant question or questions. Quotas can use one question or nested combinations and are pre-populated in the platform's Quota tab.
Q2. What is your gender?
Type: Single-Select
Response Options:
- Male
- Female
- Non-binary
- Prefer not to say
Set Quota
If "Male" at Q2, 50%
If "Female" at Q2, 50%
These are illustrative targets for two categories. Before using the fragment, define targets and the treatment of every eligible response, including "Non-binary" and "Prefer not to say", so the quota scheme matches the study population. See Setting up quotas.
Stored variables and flags
A recode groups responses to one question for reporting. A stored variable records an additional calculated value, such as a segment combining age and gender. Specify its name, input questions, conditions, and output labels.
Using Q1 and Q2 above:
Create stored variable "Age_Gen" after Q2.
Use the numeric age from Q1 and the exact response text from Q2.
If Q1 is 18-24 AND Q2 is "Male", store "18-24 Male"
If Q1 is 25-44 AND Q2 is "Male", store "25-44 Male"
If Q1 is 45-54 AND Q2 is "Male", store "45-54 Male"
If Q1 is 55-100 AND Q2 is "Male", store "55+ Male"
If Q1 is 18-24 AND Q2 is "Female", store "18-24 Female"
If Q1 is 25-44 AND Q2 is "Female", store "25-44 Female"
If Q1 is 45-54 AND Q2 is "Female", store "45-54 Female"
If Q1 is 55-100 AND Q2 is "Female", store "55+ Female"
If Q2 is "Non-binary" OR Q2 is "Prefer not to say", store "Else"
This example groups the final two responses together. Choose output categories that fit the analysis and document any grouping. See Calculated variables for stored scalar and multi-select values, or Derived questions for combining existing questions after fieldwork.
Grid Select and Grid Rating
Use Grid Select when respondents choose one labeled category per row. List columns in the order they should appear, and keep ordered scales fixed.
Q6A. How satisfied are you with each aspect of your most recent cinema visit?
Type: Grid Select Question
Rows:
- Ticket price
- Seat comfort
- Sound quality
- Concessions
Columns, in this order:
- Very dissatisfied
- Somewhat dissatisfied
- Neither satisfied nor dissatisfied
- Somewhat satisfied
- Very satisfied
Randomize rows = True
Do not randomize columns
Use Grid Rating for numeric scale points with anchor labels:
Q6B. How satisfied are you with each aspect of your most recent cinema visit?
Type: Grid Rating Question
Rows:
- Ticket price
- Seat comfort
- Sound quality
- Concessions
5-point scale from 1 to 5
Labels: "1" = "Not satisfied", "5" = "Very satisfied"
Randomize rows = True
See Grid Select Question and Grid Rating Question.
Filtered grids and shared ordering
Define the source question and filtering rule before the grid. If several questions use the same brands, state that their randomized order must be reused.
Q5. Which online merchants have you heard of?
Type: Multi-Select
Response Options:
- eBay
- Amazon
- Temu
- Etsy
- None of the above
Exclusive Options = None of the above
Fixed Options = None of the above
For Q7 and Q8, include only merchants selected at Q5.
If "None of the above" at Q5, skip Q7 and Q8.
Randomize the eligible merchants once per respondent.
Reuse that merchant row order in Q7 and Q8.
Q7. How likely are you to consider buying from each merchant?
Type: Grid Select Question
Rows: eligible merchants from Q5
Columns, in this order:
- Very unlikely
- Somewhat unlikely
- Neither likely nor unlikely
- Somewhat likely
- Very likely
Do not randomize columns
Q8. Which features does each merchant offer? Select all that apply per merchant.
Type: Multi-Select Grid Question
Rows: the same eligible merchants, in the same order as Q7
Columns:
- Free shipping
- Flash deals
- Exclusive discounts
- Handcrafted items
- Money back guarantee
- None of these
Exclusive Options = None of these
Fixed Options = None of these
Multi-select grid exclusivity applies within each row: selecting "None of these" deselects the other answers for that merchant. For an additional validation rule, state the condition and the exact message respondents should receive. See Multi Select Grid Question.
Single-item rating scales and NPS
State the number of points, first and last values, and anchor labels.
Q7. How important is price when choosing where to buy apparel?
Type: Rating Question
5-point scale from 1 to 5
Labels: "1" = "Not at all important", "5" = "Very important"
For an NPS question:
Q8. How likely are you to recommend {brand} to a friend or colleague?
Type: Net Promoter Score Question
11-point scale from 0 to 10
Labels: "0" = "Not at all likely", "10" = "Extremely likely"
Use the brand name collected earlier as the "brand" tag.
The NPS question reports the classified promoter, passive, or detractor response. If analysis needs each respondent's exact selected scale point, use a Rating Question instead. See Net Promoter Score Question for the classification rules.
Text open ends and validation
Describe what makes an acceptable answer and specify the AI quality threshold when needed. The threshold uses a 1-5 quality score.
Q9. What would make you more likely to visit a cinema in the next three months?
Type: Open-End (Text)
Ask all
Validation instructions = Give a specific reason related to cinema visits.
Quality threshold = 3
For a deterministic rule, specify a custom validator and its error message, for example: Require at least 5 characters; otherwise show "Please enter at least 5 characters." A custom validator replaces AI quality validation. See Text Question.
Ranking
Set both limits when the respondent must rank an exact number of items.
Q10. Rank your top three reasons for choosing a quick-service restaurant,
where 1 is the most important.
Type: Ranking Question
Response Options:
- Price
- Speed of service
- Menu variety
- Location / convenience
- Healthy options
- Loyalty rewards
randomize = True
Min options = 3
Max options = 3
See Ranking Question.
Tagged loops and stimulus assignment
Describe which media are eligible, how many each respondent sees, the assignment method, and the repeated questions. Use tags to identify the stimulus and its position on every response in the loop. Those tags can be used as rows, columns, or filters in reporting.
STIMULUS ASSIGNMENT
Eligible media: items with Media_Group = "Evaluation"
Exclude items with Media_Group = "Post"
Assign 4 eligible items per respondent using least-filled assignment.
Randomize the presentation order of the 4 assigned items.
LOOP: Repeat Q21-Q23 for each assigned item, in positions 1-4.
Tag every question in the loop with the stimulus file name and position.
Q21. Please review the following advertisement.
Type: Message / Media display
Show the assigned item.
For an image, require 5 seconds before the respondent can continue.
For a video, play the assigned video.
End message: "Thanks for reviewing, please press Next to continue."
Q22. Overall, how appealing is this advertisement to you?
Type: Single-Select
Response Options:
- Extremely appealing
- Very appealing
- Somewhat appealing
- Not too appealing
- Not at all appealing
Do not randomize
Q23. What worked well or did not work well about this advertisement?
Type: Open-End (Text)
Ask only for the item in Position 1.
Set up the Media_Group metadata before programming and ensure the eligible pool can supply the requested number of items. Least-fill assignment balances coverage; it is separate from a respondent quota. See Least Fill, Adding metadata to questions, and the wide and long export formats for the resulting response layout.
Numeric grids with totals
State whether totals run down columns or across rows, which earlier value they must match, and what happens if they do not match. In this fragment, collect total_cost and brand before asking the grid and carry those values as tags for piping and reporting.
Q10. Of the {total_cost} you spent with {brand}, how much was in each category?
Type: Grid Numeric Question
Rows:
- Apparel
- Shoes
- Home goods
Columns:
- Spend
Allowed range per entry = 0-1000
Auto sum columns = True
Tags = total_cost, brand
Custom validation: The sum of the Spend column must equal {total_cost}.
If the sum does not match, show:
"Please ensure the entries sum to the total you spent."
Use row totals when that matches the question's layout. Check the totals and validation in the chosen respondent experience; see Numeric Grid Question.
Media metadata and image options
Upload images and videos to the survey's Media tab and define the metadata used by the questionnaire before programming. For example, create Boolean fields named Sponsor_Tag and Narrator_Tag:
| File | Sponsor_Tag | Narrator_Tag |
|---|---|---|
| Snacks.png | True | False |
| Clothes.png | True | True |
| Dogs.mp4 | False | True |
Reference the exact field names and values in the instructions:
Ask Ad1 only for media where Narrator_Tag = True.
Ad1. Did the narrator have any impact on how this ad made you feel?
Type: Single-Select
Response Options:
- Yes
- No
- I didn't notice a narrator
For image-based answer options, name the uploaded files and specify the size and label visibility:
Logo. Which of the following brands are you aware of?
Type: Multi-Select Question
Response Options: uploaded image files
- Nike.png
- Adidas.png
- Converse.png
image_size = (100, 100)
Image label field = file_name
Show image labels = False
See Including media in your survey for upload and metadata setup. Question references describe image sizing and labels for each supported instrument.
Quick reference
| Need | Questionnaire instruction |
|---|---|
| Randomize unordered options | randomize = True |
| Keep options fixed | Fixed Options = Other (please specify), None of the above |
| Make an option exclusive | Exclusive Options = None of the above |
| Limit selections | Min options = 1 and Max options = 3, on separate lines |
| Set a qualifying simulation default | default = "qualifying response" |
| Terminate | If "<exact option>" at Q1, Term |
| Show a follow-up | If Q5 = "Yes", Show Q6 |
| Preserve order across questions | Reuse the randomized merchant order from Q7 |
Before fielding, review the programmed questions, simulation, and respondent flow using Testing and Reviewing Your Survey.