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,
"choices": [
{ "id": "opt-0001", "text": "Every day" },
{ "id": "opt-0002", "text": "A few times a week" },
{ "id": "opt-0003", "text": "Rarely or never" }
],
"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,
"display": "grid",
"rowChoices": [
{ "id": "row-0001", "text": "Taste" },
{ "id": "row-0002", "text": "Price" },
{ "id": "row-0003", "text": "Availability" }
],
"columnChoices": [
{ "id": "col-0001", "text": "Not satisfied" },
{ "id": "col-0002", "text": "Somewhat satisfied" },
{ "id": "col-0003", "text": "Very satisfied" }
],
"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",
"choices": [
{ "id": "brand-01", "text": "Blue Bottle" },
{ "id": "brand-02", "text": "Stumptown" },
{ "id": "brand-03", "text": "Lavazza" }
],
"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",
"choices": [
{ "id": "item-01", "text": "Price" },
{ "id": "item-02", "text": "Origin" },
{ "id": "item-03", "text": "Roast level" },
{ "id": "item-04", "text": "Brand" }
],
"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,
"choices": [
{ "id": "opt-0001", "text": "Every day" },
{ "id": "opt-0002", "text": "A few times a week" },
{ "id": "opt-0003", "text": "Rarely or never" }
],
"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,
"display": "grid",
"rowChoices": [
{ "id": "row-0001", "text": "Taste" },
{ "id": "row-0002", "text": "Price" },
{ "id": "row-0003", "text": "Availability" }
],
"columnChoices": [
{ "id": "col-0001", "text": "Not satisfied" },
{ "id": "col-0002", "text": "Somewhat satisfied" },
{ "id": "col-0003", "text": "Very satisfied" }
],
"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",
"choices": [
{ "id": "brand-01", "text": "Blue Bottle" },
{ "id": "brand-02", "text": "Stumptown" },
{ "id": "brand-03", "text": "Lavazza" }
],
"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",
"choices": [
{ "id": "item-01", "text": "Price" },
{ "id": "item-02", "text": "Origin" },
{ "id": "item-03", "text": "Roast level" },
{ "id": "item-04", "text": "Brand" }
],
"options": ["Price", "Origin", "Roast level", "Brand"],
"metric": "importance",
"itemsPerScreen": 4,
"concepts": []
}
]
}
Each question’s
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.
The endpoint returns the study’s latest editable revision. This can include
unpublished edits, so the questions may differ from what live participants see.
Path Parameters
string
required
The study’s
id or linkId, both returned by
List Studies.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, gabor_granger. New types may
be added, so handle unknown values.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
An array of media attachments.
Show Media Object
Show Media Object
string | null
required
An optional embed URL for the concept (e.g. a Figma or prototype link).
string
Present only when the embed cannot be loaded. The value is
media_unavailable.Multiple Choice Questions
type: "multiple_choice" questions additionally include:boolean
required
Whether the participant can select multiple options.
object[]
required
string[]
required
The option texts, in the same order as
choices. Deprecated. Use choices.Ranking Questions
type: "ranking" questions additionally include:object[]
required
The items to rank, in order. Each item has
id and text, as described for
choices above.string[]
required
The item texts, in the same order as
choices. Deprecated. Use choices.Matrix Questions
type: "matrix" questions additionally include:boolean
required
Whether multiple selections are allowed per row.
string
required
How the participant answers.
grid shows a row-by-column grid. card_sort
shows the rows as cards that the participant sorts into the columns.object[]
required
The rows rated by the participant, in order. Each row has
id and text.object[]
required
The shared answer scale that each row is rated on, in order. Each column has
id and text.string[]
required
The row texts, in the same order as
rowChoices. Deprecated. Use
rowChoices.string[]
required
The column texts, in the same order as
columnChoices. Deprecated. Use
columnChoices.MaxDiff Questions
type: "max_diff" questions additionally include:object[]
required
The items being compared, in order. Each item has
id and text.string[]
required
The item texts, in the same order as
choices. Deprecated. Use choices.string
required
What participants judge the items on (e.g. “importance”).
integer
required
How many items are shown per comparison screen.
Open-Ended Questions
type: "open_ended" questions carry the common fields. A question that is a
task also includes task.object
Present only for task questions.
Show Task Object
Show Task Object
string | null
required
The saved destination URL for the task, or
null if none is set. This
value does not include the concept URL that a task can inherit.boolean
required
Whether the task opens in a floating window on supported desktop browsers.
string
Where the task page comes from. One of:
concept, previous, custom.
Omitted when the study uses the default rules.Gabor-Granger Questions
type: "gabor_granger" questions additionally include:number[]
required
The prices shown to the participant.
string
required
The currency code for the prices.
integer
required
The lowest intent score (1 to 5) that counts as accepting a price. A score
at or above this value is an accept.
string
required
Where the first price can come from.
all lets it start anywhere on the
price ladder. middle starts it near the middle third of the ladder.File Upload and Statement Questions
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,
"choices": [
{ "id": "opt-0001", "text": "Every day" },
{ "id": "opt-0002", "text": "A few times a week" },
{ "id": "opt-0003", "text": "Rarely or never" }
],
"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,
"display": "grid",
"rowChoices": [
{ "id": "row-0001", "text": "Taste" },
{ "id": "row-0002", "text": "Price" },
{ "id": "row-0003", "text": "Availability" }
],
"columnChoices": [
{ "id": "col-0001", "text": "Not satisfied" },
{ "id": "col-0002", "text": "Somewhat satisfied" },
{ "id": "col-0003", "text": "Very satisfied" }
],
"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",
"choices": [
{ "id": "brand-01", "text": "Blue Bottle" },
{ "id": "brand-02", "text": "Stumptown" },
{ "id": "brand-03", "text": "Lavazza" }
],
"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",
"choices": [
{ "id": "item-01", "text": "Price" },
{ "id": "item-02", "text": "Origin" },
{ "id": "item-03", "text": "Roast level" },
{ "id": "item-04", "text": "Brand" }
],
"options": ["Price", "Origin", "Roast level", "Brand"],
"metric": "importance",
"itemsPerScreen": 4,
"concepts": []
}
]
}