Listen LabsDocs

    Endpoints

    Get Study Questions

    Get the participant-facing questions and concepts from a study's latest revision

    GET/api/public/v1/studies/{studyId}/questions

    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

    studyIdstringpathrequired

    The study's id or linkId, both returned by List Studies.

    Response

    questionsobject[]required

    The participant-facing questions from the study's latest editable revision. Each question has a type field that determines its shape.

    Errors

    Errors share the common envelope (error + code):

    StatusCodeMeaning
    401missing_api_key / invalid_api_keyMissing or invalid API key.
    403forbiddenThe key's user isn't a member of the key's workspace.
    404study_not_foundStudy not found in the key's workspace.
    500internal_errorInternal error (details are logged server-side, not returned).

    Example request

    Example Request
    curl 'https://listenlabs.ai/api/public/v1/studies/9b2f1c3e-0000-0000-0000-000000000000/questions' \
      -H 'x-api-key: <api_key>'

    Example response

    Response
    {
      "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": []
        }
      ]
    }