Question Type: text_question

When and Why to Use

Use this to collect open-ended responses where you want to capture thoughts, opinions, or unaided recall. It's ideal for:

Brand recall
Reasons behind choices
Open feedback

Includes built-in AI validation to ensure quality. Responses are scored 1-5, and if too weak, the respondent is prompted to clarify.

Set quality_threshold=1 to avoid any termination. Set a custom_validator to override AI scoring.

Portrait Experience

Single-line or multiline input, depending on the short flag.
Inline validation appears after submission.
Retry prompt if response doesn't meet the quality threshold.
If number_of_responses > 1, user is asked to submit multiple responses one at a time.

Landscape Experience

Supports multi-response collection if number_of_responses > 1.
Respondents can enter several distinct answers before continuing.
Retry logic and termination still apply per entry.

Configuration Options

Option	Type	Required	Default	Description
`question`	`string`	yes	-	The prompt shown to the user
`image`	`MediaItem`	no	-	Optional image from `s.media`
`default`	`string` or `list`	no	random string	Default value(s) for test data
`short`	`boolean`	no	`False`	Use a compact text field (for names, labels, etc)
`recodes`	`dict[str, str]`	no	-	Optional text recodes (not often used here)
`validation_instructions`	`string`	no	-	AI instructions for what makes a valid response
`quality_threshold`	`int`	no	`3`	Minimum score (1–5) to accept a response
`termination_threshold`	`int`	no	`1`	Below this score after retries, survey terminates
`max_attempts`	`int`	no	`3`	Number of chances to clarify a low-quality response
`custom_validator`	`Callable[[str], str	None]`	no	-
`number_of_responses`	`int`	no	`1`	Number of distinct answers to collect
`min_responses`	`int`	no	-	Minimum number of answers required
`**topics`	`dict`	no	-	Used to fill tokens in text and group questions in reports

Example Code

s.text_question("When you think about cars, which brands immediately come to mind?")

With validation and image:

s.text_question( "What do you like about {brand} cars?", topic="Ford", validation_instructions="Please provide a specific reason, not just 'they're good'", image=s.media.ford_logo )

With a custom validator:

s.text_question( "Name a car brand you would never consider buying", custom_validator=lambda x: "That doesn't sound like a brand name" if x.lower() not in known_brands else None )

Notes

AI validation is optional but enabled by default.
To disable termination, set quality_threshold=1 or handle validation errors manually.
custom_validator overrides AI validation entirely if provided.

Question Type: grid_select_question

Question Type: grid_rating_question

Question Type: grid_numeric_question

Question Type: this_or_that_rating_question

Question Type: net_promoter_score_question