These endpoints are legacy. They use the unversioned /api/public/... paths. For new integrations, use the versioned API (/api/public/v1/...). The create, launch, and wallet endpoints are documented there only.

These four endpoints read study data. They authenticate with the x-api-key header (see Get API Access). The link_id path parameter also accepts the study’s id.

List Studies

This endpoint lists the studies in the key’s organization. It returns up to 5000 studies, newest first. It doesn’t support paging. GET https://listenlabs.ai/api/public/list_surveys

Response

Returns an array. Each study is an object with the following fields: id uuid Permanent unique identifier for the study. It never changes. Accepted by the versioned launch, questions, and response endpoints. link_id string The link ID of the study. This is the path parameter for the Get Responses, Get Single Response, and Get Study Questions endpoints. You can edit it in the study settings, so it might change. title string The title of the study. Returns "Untitled" when the study has no title. created_at string UTC timestamp of when the study was created. desc string A short description in the form "{title} ({count} Responses)". The count is the number of completed responses.

Errors

Status	Meaning
`401`	The API key is missing or invalid.

Example Request

curl 'https://listenlabs.ai/api/public/list_surveys' \
  -H 'x-api-key: <api_key>'

Example Response

[
  {
    "id": "12345678-0000-0000-0000-000000000000",
    "link_id": "study-1",
    "title": "Example study",
    "created_at": "2023-09-02T07:07:17.960725+00:00",
    "desc": "Example study (12 Responses)"
  },
  {
    "id": "23456789-0000-0000-0000-000000000000",
    "link_id": "study-2",
    "title": "Example study 2",
    "created_at": "2023-09-01T07:07:17.960725+00:00",
    "desc": "Example study 2 (9 Responses)"
  }
]

Get Responses

This endpoint lists the responses for a study. Responses marked as ignored and test responses are not returned. GET https://listenlabs.ai/api/public/responses/{link_id}

Path Parameters

link_id string The link ID or the id of the study. You can find the link ID in the study URL or with the List Studies endpoint. For example, in https://listenlabs.ai/s/abc123 the link ID is abc123.

Query Parameters

page integer default:"0" The page number, starting at 0. per_page integer default:"1000" Number of responses to return per page. Values above 10000 are reduced to 10000. updated_since string ISO 8601 date string. Returns responses updated at or after this time (e.g., 2023-08-18T11:51:54.649916Z). include_in_progress boolean default:"true" Set to false to leave out responses that are still in progress.

Paging

A response is left out when it has no answers. This happens after each page loads. A page can therefore have fewer items than per_page, even when more responses exist. Keep requesting the next page until a page is empty.

Response

Returns an array of responses. Each response is an object with the following fields: id uuid Unique identifier for the response. response_number number The ordered number of the response. created_at string UTC timestamp of when the response was created. updated_at string UTC timestamp of when the response was last updated. When an analysis finish time exists, this field shows that time instead. progress string The completion progress of the response: "complete", "in_progress", or "screened_out". response_duration_seconds number The total duration of the response in whole seconds. answers object Answers to the study’s questions. Keyed by question title, with no number prefix. Each value is everything the participant said in response to that question. There is no summary key: use tagline and bullet_summary for summaries. answers_array Answer[] Answers to the study’s questions as an array, in the same order as the study’s CSV export.

answer_id string: The answer ID. Matches the answer_id on transcript rows from the Get Single Response endpoint.
discussion_guide_question_id string | null: The question ID. Matches the id field from the Get Study Questions endpoint. Null when the answer isn’t tied to a question.
concept_id string | null: The concept ID. Null if the answer isn’t concept-specific.
question string: The question title. Prefixed with its number when one is available (e.g. "Q1: What is your age?").
answer string: The answer to the question.
option_ids string[]: The IDs of the options the participant selected. These match the id values in the choices list from Get Study Questions. Empty for open-ended answers and matrix questions.
matrix_selections object[]: For matrix questions. Each entry has row_id and column_id, which match the id values in the row_choices and column_choices lists. Empty for other question types.
question_id string deprecated: Deprecated. Use answer_id instead.

attributes object The visible URL parameters passed to the study. Some parameters are hidden.

id string: An ID passed to the study, e.g. https://listenlabs.ai/s/abc123?id=123.

short_transcript string | null A transcript of the entire conversation where the assistant messages are shortened to a couple of words. Null if the transcript has not been generated yet. The fields below appear only when the response has a value for them. short_assistant_messages string[] Condensed assistant turns used to build compact transcript context. bullet_summary string[] Concise bullet-point summary of the response. tags string[] Extracted keyword labels for the response. tagline string Short one-line synthesis for the response. summary string A natural-language summary of the response. quality_score number | string Response quality score, typically on a 1-5 scale. other_remarks string and personas string Additional remarks and the persona classification.

Errors

Status	Meaning
`401`	The API key is missing or invalid. The body contains an `error` message.
`404`	The study was not found, or the key’s organization can’t read it. The body contains `{ "error": "Survey not found or no access" }`.

Example Request

curl 'https://listenlabs.ai/api/public/responses/study123?page=0&per_page=100&updated_since=2023-08-18T00:00:00Z' \
  -H 'x-api-key: <api_key>'

Example Response

[
  {
    "id": "12345678-0000-0000-0000-000000000000",
    "response_number": 1,
    "created_at": "2023-08-18T11:51:54.649916+00:00",
    "updated_at": "2023-08-18T12:05:30.123456+00:00",
    "progress": "complete",
    "response_duration_seconds": 245,
    "answers": {
      "Question 1": "Answer of question 1",
      "Question 2": "Answer of question 2"
    },
    "answers_array": [
      {
        "answer_id": "f1e2d3c4-0000-0000-0000-000000000001",
        "discussion_guide_question_id": "a1b2c3d4-0000-0000-0000-000000000001",
        "concept_id": null,
        "question_id": "f1e2d3c4-0000-0000-0000-000000000001",
        "question": "Question 1",
        "answer": "Answer of question 1"
      },
      {
        "answer_id": "f1e2d3c4-0000-0000-0000-000000000002",
        "discussion_guide_question_id": "a1b2c3d4-0000-0000-0000-000000000002",
        "concept_id": "b2c3d4e5-0000-0000-0000-000000000001",
        "question_id": "f1e2d3c4-0000-0000-0000-000000000002",
        "question": "Question 2",
        "answer": "Answer of question 2"
      }
    ],
    "attributes": {
      "id": "123"
    },
    "short_transcript": "• Welcome → Start\n• Ask for name → John\n• Thank you, bye →",
    "short_assistant_messages": ["Welcome and intro", "Asked for name", "Thanked and closed"],
    "bullet_summary": ["Bullet summary of response 1"],
    "quality_score": 5,
    "tags": ["tag-1", "tag-2"],
    "tagline": "Tagline of response 1",
    "summary": "Summary of response 1"
  },
  {
    "id": "23456789-0000-0000-0000-000000000000",
    "response_number": 2,
    "created_at": "2023-08-19T11:51:54.649916+00:00",
    "updated_at": "2023-08-19T12:10:15.789012+00:00",
    "progress": "complete",
    "response_duration_seconds": 312,
    "answers": {
      "Question 1": "Answer of question 1",
      "Question 2": "Answer of question 2"
    },
    "answers_array": [
      {
        "answer_id": "f1e2d3c4-0000-0000-0000-000000000001",
        "discussion_guide_question_id": "a1b2c3d4-0000-0000-0000-000000000001",
        "concept_id": null,
        "question_id": "f1e2d3c4-0000-0000-0000-000000000001",
        "question": "Question 1",
        "answer": "Answer of question 1"
      },
      {
        "answer_id": "f1e2d3c4-0000-0000-0000-000000000002",
        "discussion_guide_question_id": "a1b2c3d4-0000-0000-0000-000000000002",
        "concept_id": null,
        "question_id": "f1e2d3c4-0000-0000-0000-000000000002",
        "question": "Question 2",
        "answer": "Answer of question 2"
      }
    ],
    "attributes": {
      "id": "567"
    },
    "short_transcript": "• Welcome → Start\n• Ask for name → Alice\n• Thank you, bye →",
    "short_assistant_messages": ["Welcome and intro", "Asked for name", "Thanked and closed"],
    "bullet_summary": ["Bullet summary of response 2"],
    "quality_score": 4,
    "tags": ["tag-1", "tag-3"],
    "tagline": "Tagline of response 2",
    "summary": "Summary of response 2"
  }
]

Get Single Response

This endpoint retrieves a single response for a study. GET https://listenlabs.ai/api/public/responses/{link_id}/{response_id}

Path Parameters

link_id string The link ID or the id of the study. For example, in https://listenlabs.ai/s/abc123 the link ID is abc123. response_id string The unique ID of the response you want to retrieve.

Response

Returns a single response with the following fields: id string The response ID from the path. survey string The study identifier from the path, as you sent it. transcript array A complete transcript of the conversation, with each entry containing:

moderator string: The message from the assistant/moderator.
user string: The response from the user.
discussion_guide_question_id string | null: The question ID for this row. Matches the id field from the Get Study Questions endpoint. Null for non-question rows (e.g. intro messages).
concept_id string | null: The concept ID for this row. Null if the question isn’t concept-specific.
answer_id string | null: The answer ID for this question. Matches the answer_id in the Get Responses endpoint’s answers_array. Null for non-question rows.
response_index number: The zero-based index of this row in the conversation history.
is_followup boolean: Whether this row is a follow-up to the same question as the previous row.
audio string | null: A signed URL to the audio recording of the user’s response. The URL is valid for 1 hour. Null if no audio recording exists. Null for redacted rows.
video object | null: Video playback information. Null if no video recording exists. Null for redacted rows.
- stream_url string: HLS stream URL for the video recording.
- mp4_url string: Direct MP4 download URL for the video recording.
question_uuid string deprecated: Deprecated. Use discussion_guide_question_id instead.

Errors

Status	Meaning
`401`	The API key is missing or invalid. The body contains an `error` message.
`404`	The response was not found for this study. The body contains `{ "error": "Response not found" }`.
`500`	The response could not be read. The body contains an `error` message.

Example Request

curl 'https://listenlabs.ai/api/public/responses/study-1/12345678-0000-0000-0000-000000000000' \
  -H 'x-api-key: <api_key>'

Example Response: Audio and Text

{
  "id": "12345678-0000-0000-0000-000000000000",
  "survey": "audio-survey",
  "transcript": [
    {
      "moderator": "Welcome to our audio interview. Can you describe your experience with our product?",
      "user": "The product has been very helpful for our team's workflow.",
      "discussion_guide_question_id": "a1b2c3d4-0000-0000-0000-000000000001",
      "concept_id": null,
      "answer_id": "f1e2d3c4-0000-0000-0000-000000000001",
      "response_index": 0,
      "is_followup": false,
      "audio": "https://storage.listenlabs.ai/audio/responses/abc123.mp3?token=...",
      "video": null,
      "question_uuid": "a1b2c3d4-0000-0000-0000-000000000001"
    },
    {
      "moderator": "What specific features do you find most useful?",
      "user": "The task management and integration capabilities are standouts for us.",
      "discussion_guide_question_id": "a1b2c3d4-0000-0000-0000-000000000002",
      "concept_id": "b2c3d4e5-0000-0000-0000-000000000001",
      "answer_id": "f1e2d3c4-0000-0000-0000-000000000002",
      "response_index": 1,
      "is_followup": false,
      "audio": "https://storage.listenlabs.ai/audio/responses/def456.mp3?token=...",
      "video": null,
      "question_uuid": "a1b2c3d4-0000-0000-0000-000000000002"
    }
  ]
}

Example Response: Video and Text

{
  "id": "23456789-0000-0000-0000-000000000000",
  "survey": "video-interview",
  "transcript": [
    {
      "moderator": "Tell us about your background in the industry.",
      "user": "I've been working in software development for over 10 years, primarily focusing on frontend technologies.",
      "discussion_guide_question_id": "a1b2c3d4-0000-0000-0000-000000000001",
      "concept_id": null,
      "answer_id": "f1e2d3c4-0000-0000-0000-000000000001",
      "response_index": 0,
      "is_followup": false,
      "audio": null,
      "video": {
        "stream_url": "https://stream.mux.com/vWx123.m3u8",
        "mp4_url": "https://stream.mux.com/vWx123/capped-1080p.mp4"
      },
      "question_uuid": "a1b2c3d4-0000-0000-0000-000000000001"
    },
    {
      "moderator": "What attracted you to our company?",
      "user": "Your focus on innovative solutions and strong company culture really resonated with me.",
      "discussion_guide_question_id": "a1b2c3d4-0000-0000-0000-000000000002",
      "concept_id": null,
      "answer_id": "f1e2d3c4-0000-0000-0000-000000000002",
      "response_index": 1,
      "is_followup": false,
      "audio": null,
      "video": {
        "stream_url": "https://stream.mux.com/yZ456.m3u8",
        "mp4_url": "https://stream.mux.com/yZ456/capped-1080p.mp4"
      },
      "question_uuid": "a1b2c3d4-0000-0000-0000-000000000002"
    }
  ]
}

Example Response: Text Only

{
  "id": "34567890-0000-0000-0000-000000000000",
  "survey": "text-feedback",
  "transcript": [
    {
      "moderator": "How would you rate your satisfaction with our customer service?",
      "user": "I would rate it 9/10. Your support team was quick to respond and very helpful.",
      "discussion_guide_question_id": "a1b2c3d4-0000-0000-0000-000000000001",
      "concept_id": null,
      "answer_id": "f1e2d3c4-0000-0000-0000-000000000001",
      "response_index": 0,
      "is_followup": false,
      "audio": null,
      "video": null,
      "question_uuid": "a1b2c3d4-0000-0000-0000-000000000001"
    },
    {
      "moderator": "What suggestions do you have for improvement?",
      "user": "It would be nice to have weekend support hours for urgent issues.",
      "discussion_guide_question_id": "a1b2c3d4-0000-0000-0000-000000000002",
      "concept_id": null,
      "answer_id": "f1e2d3c4-0000-0000-0000-000000000002",
      "response_index": 1,
      "is_followup": false,
      "audio": null,
      "video": null,
      "question_uuid": "a1b2c3d4-0000-0000-0000-000000000002"
    }
  ]
}

Get Study Questions

This endpoint retrieves the questions for a study. It returns the questions from the study’s latest revision, which can include unpublished edits. GET https://listenlabs.ai/api/public/studies/{study_id}/questions The field names in this response use snake_case. The versioned endpoint, Get Study Questions, returns the same data with camelCase names.

Path Parameters

study_id string The link ID or the id of the study. You can find the link ID in the study URL or with the List Studies endpoint.

Response

Returns an object with a questions array. Each question has a type field that determines its shape. Conjoint questions are not returned. questions array All question types share these base fields:

id string: Unique identifier for the question. Matches the discussion_guide_question_id field in the Get Responses and Get Single Response endpoints.
text string: The question text shown to participants.
is_screener boolean: Whether this question is part of the screening section.
type string: One of open_ended, file_upload, multiple_choice, ranking, statement, matrix, max_diff, or gabor_granger.
question_number number: The human-readable question number for display purposes.
concepts array: The concepts attached to this question (empty if the question is not part of a concept test block). Each concept contains:
- id string: Unique identifier for the concept.
- title string: The concept title.
- description string: The concept description.
- media array: Media attachments. Each has a type (image or video), a name, and a url (may be null). An error of media_unavailable is set when the file can’t be loaded.
- embed_url string | null: An optional embed URL for the concept (e.g. a Figma or prototype link).
- embed_error string: Present only when the embed can’t be loaded. The value is media_unavailable.

Other fields depend on the type:

multiple_choice: is_multi_select boolean, options string[], and choices object[]. Each choice has an id and text.
ranking: options string[] and choices object[]. The items to rank.
matrix: is_multi_select boolean, display string (grid or card_sort), rows string[], columns string[], row_choices object[], and column_choices object[]. Each choice has an id and text.
max_diff: options string[], choices object[], metric string, and items_per_screen number.
open_ended: task object, present only for task questions. It has url string | null, pip_enabled boolean, and destination_source string (concept, previous, or custom, when set).
gabor_granger: price_points number[], currency_code string, accept_intent_threshold number, and start_price_range string (all or middle).
file_upload and statement: base fields only.

Errors

Status	Meaning
`401`	The API key is missing or invalid. The body contains an `error` message.
`404`	The study was not found, or the key’s organization can’t read it. The body contains `{ "error": "Study not found or no access" }`.

Example Request

curl 'https://listenlabs.ai/api/public/studies/my-study/questions' \
  -H 'x-api-key: <api_key>'

Example Response

{
  "questions": [
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000001",
      "text": "What is your age range?",
      "is_screener": true,
      "question_number": 1,
      "type": "multiple_choice",
      "is_multi_select": false,
      "options": ["18-24", "25-34", "35-44", "45-54", "55+"],
      "choices": [
        { "id": "opt-0001", "text": "18-24" },
        { "id": "opt-0002", "text": "25-34" },
        { "id": "opt-0003", "text": "35-44" },
        { "id": "opt-0004", "text": "45-54" },
        { "id": "opt-0005", "text": "55+" }
      ],
      "concepts": []
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000002",
      "text": "Tell us about your experience with our product.",
      "is_screener": false,
      "question_number": 2,
      "type": "open_ended",
      "concepts": []
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000003",
      "text": "Rank the following features by importance.",
      "is_screener": false,
      "question_number": 3,
      "type": "ranking",
      "options": ["Ease of use", "Performance", "Price", "Customer support"],
      "choices": [
        { "id": "feat-01", "text": "Ease of use" },
        { "id": "feat-02", "text": "Performance" },
        { "id": "feat-03", "text": "Price" },
        { "id": "feat-04", "text": "Customer support" }
      ],
      "concepts": []
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000004",
      "text": "Thank you for your feedback. We will now ask about your preferences.",
      "is_screener": false,
      "question_number": 4,
      "type": "statement",
      "concepts": []
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000005",
      "text": "Which categories interest you? Select all that apply.",
      "is_screener": false,
      "question_number": 5,
      "type": "multiple_choice",
      "is_multi_select": true,
      "options": ["Technology", "Health", "Finance", "Education", "Entertainment"],
      "choices": [
        { "id": "cat-01", "text": "Technology" },
        { "id": "cat-02", "text": "Health" },
        { "id": "cat-03", "text": "Finance" },
        { "id": "cat-04", "text": "Education" },
        { "id": "cat-05", "text": "Entertainment" }
      ],
      "concepts": []
    }
  ]
}

Legacy

Legacy Endpoints

List Studies

Response

Errors

Example Request

Example Response

Get Responses

Path Parameters

Query Parameters

Paging

Response

Errors

Example Request

Example Response

Get Single Response

Path Parameters

Response

Errors

Example Request

Example Response: Audio and Text

Example Response: Video and Text

Example Response: Text Only

Get Study Questions

Path Parameters

Response

Errors

Example Request

Example Response

​List Studies

​Response

​Errors

​Example Request

​Example Response

​Get Responses

​Path Parameters

​Query Parameters

​Paging

​Response

​Errors

​Example Request

​Example Response

​Get Single Response

​Path Parameters

​Response

​Errors

​Example Request

​Example Response: Audio and Text

​Example Response: Video and Text

​Example Response: Text Only

​Get Study Questions

​Path Parameters

​Response

​Errors

​Example Request

​Example Response

List Studies

Response

Errors

Example Request

Example Response

Get Responses

Path Parameters

Query Parameters

Paging

Response

Errors

Example Request

Example Response

Get Single Response

Path Parameters

Response

Errors

Example Request

Example Response: Audio and Text

Example Response: Video and Text

Example Response: Text Only

Get Study Questions

Path Parameters

Response

Errors

Example Request

Example Response