curl 'https://listenlabs.ai/api/public/v1/studies/9b2f1c3e-0000-0000-0000-000000000000/questions' \
-H 'x-api-key: <api_key>'
{
"questions": [
{
"id": "a1b2c3d4-0000-0000-0000-000000000001",
"text": "How often do you drink coffee?",
"isScreener": true,
"questionNumber": 1,
"type": "multiple_choice",
"isMultiSelect": false,
"options": ["Every day", "A few times a week", "Rarely or never"],
"concepts": []
},
{
"id": "a1b2c3d4-0000-0000-0000-000000000002",
"text": "Tell me about the last time you tried a new coffee brand.",
"isScreener": false,
"questionNumber": 2,
"type": "open_ended",
"concepts": []
},
{
"id": "a1b2c3d4-0000-0000-0000-000000000003",
"text": "What's your first impression of this design?",
"isScreener": false,
"questionNumber": 3,
"type": "open_ended",
"concepts": [
{
"id": "c1d2e3f4-0000-0000-0000-000000000001",
"title": "Minimal design",
"description": "Clean white packaging with a single accent color.",
"media": [
{
"type": "image",
"name": "minimal.png",
"url": "https://example.com/minimal.png"
}
],
"embedUrl": null
}
]
},
{
"id": "a1b2c3d4-0000-0000-0000-000000000004",
"text": "How satisfied are you with each of the following?",
"isScreener": false,
"questionNumber": 4,
"type": "matrix",
"isMultiSelect": false,
"rows": ["Taste", "Price", "Availability"],
"columns": ["Not satisfied", "Somewhat satisfied", "Very satisfied"],
"concepts": []
},
{
"id": "a1b2c3d4-0000-0000-0000-000000000005",
"text": "Rank these brands from most to least trusted.",
"isScreener": false,
"questionNumber": 5,
"type": "ranking",
"options": ["Blue Bottle", "Stumptown", "Lavazza"],
"concepts": []
},
{
"id": "a1b2c3d4-0000-0000-0000-000000000006",
"text": "Which of these matters most and least when choosing a coffee?",
"isScreener": false,
"questionNumber": 6,
"type": "max_diff",
"options": ["Price", "Origin", "Roast level", "Brand"],
"metric": "importance",
"itemsPerScreen": 4,
"concepts": []
}
]
}
Get Study Questions
Get the participant-facing questions and concepts from a study’s latest revision
GET
/
api
/
public
/
v1
/
studies
/
{studyId}
/
questions
curl 'https://listenlabs.ai/api/public/v1/studies/9b2f1c3e-0000-0000-0000-000000000000/questions' \
-H 'x-api-key: <api_key>'
{
"questions": [
{
"id": "a1b2c3d4-0000-0000-0000-000000000001",
"text": "How often do you drink coffee?",
"isScreener": true,
"questionNumber": 1,
"type": "multiple_choice",
"isMultiSelect": false,
"options": ["Every day", "A few times a week", "Rarely or never"],
"concepts": []
},
{
"id": "a1b2c3d4-0000-0000-0000-000000000002",
"text": "Tell me about the last time you tried a new coffee brand.",
"isScreener": false,
"questionNumber": 2,
"type": "open_ended",
"concepts": []
},
{
"id": "a1b2c3d4-0000-0000-0000-000000000003",
"text": "What's your first impression of this design?",
"isScreener": false,
"questionNumber": 3,
"type": "open_ended",
"concepts": [
{
"id": "c1d2e3f4-0000-0000-0000-000000000001",
"title": "Minimal design",
"description": "Clean white packaging with a single accent color.",
"media": [
{
"type": "image",
"name": "minimal.png",
"url": "https://example.com/minimal.png"
}
],
"embedUrl": null
}
]
},
{
"id": "a1b2c3d4-0000-0000-0000-000000000004",
"text": "How satisfied are you with each of the following?",
"isScreener": false,
"questionNumber": 4,
"type": "matrix",
"isMultiSelect": false,
"rows": ["Taste", "Price", "Availability"],
"columns": ["Not satisfied", "Somewhat satisfied", "Very satisfied"],
"concepts": []
},
{
"id": "a1b2c3d4-0000-0000-0000-000000000005",
"text": "Rank these brands from most to least trusted.",
"isScreener": false,
"questionNumber": 5,
"type": "ranking",
"options": ["Blue Bottle", "Stumptown", "Lavazza"],
"concepts": []
},
{
"id": "a1b2c3d4-0000-0000-0000-000000000006",
"text": "Which of these matters most and least when choosing a coffee?",
"isScreener": false,
"questionNumber": 6,
"type": "max_diff",
"options": ["Price", "Origin", "Roast level", "Brand"],
"metric": "importance",
"itemsPerScreen": 4,
"concepts": []
}
]
}
Replaces the legacy
GET /api/public/studies/{study_id}/questions
endpoint, deprecated starting August 1, 2026.id matches the discussionGuideQuestionId field in the
response endpoints, so you can join questions with
their corresponding answers and transcript rows — see the
Data Map.
Path Parameters
string
required
The study’s
id or linkId, both returned by
List Studies. The legacy endpoint accepts only the
linkId.Response
object[]
required
The participant-facing questions from the study’s latest editable revision.
Each question has a
type field that determines its shape.Show Question Types
Show Question Types
Common Fields
All question types share these base fields:string
required
Unique identifier for the question. Matches the
discussionGuideQuestionId
field in the response endpoints, enabling you to join questions with their
corresponding transcript rows and answers.string
required
The question text shown to participants.
boolean
required
Whether this question is part of the screening section.
string
required
The question type. One of:
open_ended, file_upload, multiple_choice,
ranking, statement, matrix, max_diff.integer
required
The human-readable question number (1-based) for display purposes.
object[]
required
An array of concept objects attached to this question (empty if the question
is not part of a concept test block).
Show Concept Object
Show Concept Object
string
required
Unique identifier for the concept. Referenced by
conceptId on answers
and transcript rows.string
required
The concept title.
string
required
The concept description.
object[]
required
string | null
required
An optional embed URL for the concept (e.g. a Figma or prototype link).
Multiple Choice Questions
type: "multiple_choice" questions additionally include:boolean
required
Whether the participant can select multiple options.
string[]
required
The list of answer options.
Ranking Questions
type: "ranking" questions additionally include:string[]
required
The list of items to rank.
Matrix Questions
type: "matrix" questions additionally include:boolean
required
Whether multiple selections are allowed per row.
string[]
required
The row labels rated by the participant.
string[]
required
The column labels each row is rated across.
MaxDiff Questions
type: "max_diff" questions additionally include:string[]
required
The items being compared.
string
required
What participants judge the items on (e.g. “importance”).
integer
required
How many items are shown per comparison screen.
Open-Ended, File Upload & Statement Questions
type: "open_ended", type: "file_upload", and type: "statement" questions
carry only the common fields.Errors
Errors share the common envelope (error + code):
| Status | Code | Meaning |
|---|---|---|
401 | missing_api_key / invalid_api_key | Missing or invalid API key. |
403 | forbidden | The key’s user isn’t a member of the key’s organization. |
404 | study_not_found | Study not found in the key’s organization. |
500 | internal_error | Internal error (details are logged server-side, not returned). |
curl 'https://listenlabs.ai/api/public/v1/studies/9b2f1c3e-0000-0000-0000-000000000000/questions' \
-H 'x-api-key: <api_key>'
{
"questions": [
{
"id": "a1b2c3d4-0000-0000-0000-000000000001",
"text": "How often do you drink coffee?",
"isScreener": true,
"questionNumber": 1,
"type": "multiple_choice",
"isMultiSelect": false,
"options": ["Every day", "A few times a week", "Rarely or never"],
"concepts": []
},
{
"id": "a1b2c3d4-0000-0000-0000-000000000002",
"text": "Tell me about the last time you tried a new coffee brand.",
"isScreener": false,
"questionNumber": 2,
"type": "open_ended",
"concepts": []
},
{
"id": "a1b2c3d4-0000-0000-0000-000000000003",
"text": "What's your first impression of this design?",
"isScreener": false,
"questionNumber": 3,
"type": "open_ended",
"concepts": [
{
"id": "c1d2e3f4-0000-0000-0000-000000000001",
"title": "Minimal design",
"description": "Clean white packaging with a single accent color.",
"media": [
{
"type": "image",
"name": "minimal.png",
"url": "https://example.com/minimal.png"
}
],
"embedUrl": null
}
]
},
{
"id": "a1b2c3d4-0000-0000-0000-000000000004",
"text": "How satisfied are you with each of the following?",
"isScreener": false,
"questionNumber": 4,
"type": "matrix",
"isMultiSelect": false,
"rows": ["Taste", "Price", "Availability"],
"columns": ["Not satisfied", "Somewhat satisfied", "Very satisfied"],
"concepts": []
},
{
"id": "a1b2c3d4-0000-0000-0000-000000000005",
"text": "Rank these brands from most to least trusted.",
"isScreener": false,
"questionNumber": 5,
"type": "ranking",
"options": ["Blue Bottle", "Stumptown", "Lavazza"],
"concepts": []
},
{
"id": "a1b2c3d4-0000-0000-0000-000000000006",
"text": "Which of these matters most and least when choosing a coffee?",
"isScreener": false,
"questionNumber": 6,
"type": "max_diff",
"options": ["Price", "Origin", "Roast level", "Brand"],
"metric": "importance",
"itemsPerScreen": 4,
"concepts": []
}
]
}
⌘I