Skip to main content

​
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)"
                                                }
                                                ]