Use qualitative_text_question for an adaptive open end whose follow-up questions should depend on the respondent's answers. For study-design guidance and the complete fielding-to-analysis workflow, see Running qualitative text interviews.
Example
s.qualitative_text_question(
"What makes choosing a current account difficult?",
instructions=(
"Understand the moments that create uncertainty and the trade-offs "
"people make."
),
max_follow_ups=3,
id="current-account-difficulties",
)
The opening question is shown to the respondent. instructions is a private researcher brief used to guide probing. max_follow_ups limits the number of AI-generated questions after the opening turn, and id supplies the stable reporting ID shared by every turn.
The generated Survey API reference is authoritative for the full signature, supported arguments, defaults, and return type.
Interview behavior
After each answered turn, the AI receives the opening question, optional instructions, and all answered turns in order. It either asks one focused follow-up or completes the interview. It can complete before the configured bound; after the final allowed follow-up, the interview ends without requesting another AI decision.
The call returns the opening answer as an ordinary StringResponse. Follow-up answers are also stored as string responses. They have unique element IDs but share the interview's reporting ID and include their exact prompt and zero-based turn order as response metadata.
Live and simulated execution
Live interviews use OpenAI to choose each next action. Each possible follow-up requires an external AI decision, so a lower bound reduces respondent effort and caps possible AI calls.
Simulated execution is deterministic and makes no external AI calls. It exercises the bounded multi-turn flow with placeholder content; do not use simulated wording or answers to judge the quality of live interviews.
Resume and reporting
Answered turns and AI decisions are persisted. If a respondent resumes, MX8 Labs reconstructs the ordered transcript and continues without discarding or duplicating completed turns.
For analysis, MX8 Labs assembles all turns with the same respondent and reporting ID into one transcript. Coding, frequencies, and Example Verbatims treat that transcript as one respondent-level open end. Raw response outputs retain each underlying turn, including its prompt and turn order.
Limitations
This instrument does not provide a fixed sequence of stages, configurable closing copy, live moderator takeover, or voice or video interviewing. Use an ordinary text_question when you need one static open end or response validation rather than adaptive probing.