Documentation Index
Fetch the complete documentation index at: https://docs.listenlabs.ai/llms.txt
Use this file to discover all available pages before exploring further.
Get Responses
This endpoint lists all responses for a given study.
GET https://listenlabs.ai/api/public/responses/{link_id}
Path Parameters
link_id string
The link ID of the study. You can find this in the study URL or via 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 for pagination.
per_page integer default:"1000"
Number of responses to return per page.
updated_since string
ISO 8601 date string to filter responses updated after this date (e.g., 2023-08-18T11:51:54.649916Z).
include_in_progress boolean default:"true"
Whether to include responses that who’s analysis is still in progress.
Response
Returns a list of responses for the given study. 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.
answers object
Answers to all questions of the study.
Summary string — A summary of the entire conversation. Available for all studys.Question 1 string — Everything the user said in response to question 1.Question 2 string — Everything the user said in response to question 2.
answers_array Response[]
Answers to all questions of the study as an array.
answer_id string — The answer ID. Matches the answer_id on transcript rows from the single response endpoint, enabling cross-referencing.discussion_guide_question_id string — The discussion guide question ID.concept_id string | null — The concept ID. Null if not concept-specific.question_id string deprecated — Deprecated. Use answer_id instead.question string — The question text.answer string — The answer to the question.
attributes object
URL parameters that were passed to the study.
id string — An id that is passed to study e.g. https://listenlabs.ai/s/abc123?id=123.
short_transcript string
A transcript of the entire conversation where the assistant messages are shortened to a couple of words.
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",
"created_at": "2023-08-18T11:51:54.649916+00:00",
"answers": {
"Summary": "Summary of response 1",
"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": "q-001",
"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": "q-002",
"question": "Question 2",
"answer": "Answer of question 2"
}
],
"attributes": {
"id": "123"
},
"short_transcript": "• Welcome → Start\n• Ask for name → John\n• Thank you, bye →"
},
{
"id": "23456789-0000-0000-0000-000000000000",
"created_at": "2023-08-19T11:51:54.649916+00:00",
"answers": {
"Summary": "Summary of response 2",
"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": "q-001",
"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": "q-002",
"question": "Question 2",
"answer": "Answer of question 2"
}
],
"attributes": {
"id": "567"
},
"short_transcript": "• Welcome → Start\n• Ask for name → Alice\n• Thank you, bye →"
}
]
Get Single Response
This endpoint retrieves a single response for a specific study.
GET https://listenlabs.ai/api/public/responses/{link_id}/{response_id}
Path Parameters
link_id string
The link ID of the study. You can find this in the study URL or via the List Studies endpoint. For example, in https://listenlabs.ai/s/abc123 the link ID is abc123.
response_id string
The unique ID of the specific response you want to retrieve.
Response
Returns a single response with detailed information:
id string
Unique identifier for the response.
survey string
The link ID of the survey this response belongs to.
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 — The discussion guide question ID for this row.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 list endpoint’s answers_array, enabling cross-referencing between endpoints.audio string — A signed URL to the audio recording of the user’s response, if available. This URL is valid for 1 hour.video object — Video playback information, if available. If no video recording exists, this will be null.
-
stream_url string — HLS stream URL for the video recording.
mp4_url string — Direct MP4 download URL for the video recording.
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 survey. 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",
"audio": "https://storage.listenlabs.ai/audio/responses/abc123.mp3?token=...",
"video": null
},
{
"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",
"audio": "https://storage.listenlabs.ai/audio/responses/def456.mp3?token=...",
"video": null
}
]
}
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",
"audio": null,
"video": {
"stream_url": "https://stream.mux.com/vWx123.m3u8",
"mp4_url": "https://stream.mux.com/vWx123/capped-1080p.mp4"
}
},
{
"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",
"audio": null,
"video": {
"stream_url": "https://stream.mux.com/yZ456.m3u8",
"mp4_url": "https://stream.mux.com/yZ456/capped-1080p.mp4"
}
}
]
}
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",
"audio": null,
"video": null
},
{
"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",
"audio": null,
"video": null
}
]
}
List Studies
This endpoint lists all studies.
GET https://listenlabs.ai/api/public/list_surveys
Response
Returns a list of studies. Each study is an object with the following fields:
id uuid
Permanent unique identifier for the study.
link_id string
The link id of the study. This is editable in the study settings so it might change.
title string
The title of the study.
created_at string
UTC timestamp of when the study was created.
desc string
A description of the study. E.g. “My study (10 Responses)”.
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)"
}
]
