Get Responses

This endpoint lists all responses for a given study.

GET /api/public/responses/{link_id}

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>'

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": {
      "Q1: What is your name?": "My name is John.",
      "Q2: How was your experience?": "It was great, very intuitive."
    },
    "answers_array": [
      {
        "answer_id": "f1e2d3c4-0000-0000-0000-000000000001",
        "discussion_guide_question_id": "a1b2c3d4-0000-0000-0000-000000000001",
        "concept_id": null,
        "question": "Q1: What is your name?",
        "answer": "My name is John.",
        "question_id": "f1e2d3c4-0000-0000-0000-000000000001"
      },
      {
        "answer_id": "f1e2d3c4-0000-0000-0000-000000000002",
        "discussion_guide_question_id": "a1b2c3d4-0000-0000-0000-000000000002",
        "concept_id": "b2c3d4e5-0000-0000-0000-000000000001",
        "question": "Q2: How was your experience?",
        "answer": "It was great, very intuitive.",
        "question_id": "f1e2d3c4-0000-0000-0000-000000000002"
      }
    ],
    "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",
      "Asked for experience"
    ],
    "bullet_summary": [
      "Participant reported a positive overall experience.",
      "Product was described as intuitive."
    ],
    "quality_score": 5,
    "tags": ["onboarding", "ux", "intuitive"],
    "tagline": "Positive experience with intuitive UX",
    "summary": "John had a positive experience and found the product intuitive."
  },
  {
    "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": {
      "Q1: What is your name?": "I'm Alice.",
      "Q2: How was your experience?": "Overall positive, but the onboarding could be smoother."
    },
    "answers_array": [
      {
        "answer_id": "f1e2d3c4-0000-0000-0000-000000000001",
        "discussion_guide_question_id": "a1b2c3d4-0000-0000-0000-000000000001",
        "concept_id": null,
        "question": "Q1: What is your name?",
        "answer": "I'm Alice.",
        "question_id": "f1e2d3c4-0000-0000-0000-000000000001"
      },
      {
        "answer_id": "f1e2d3c4-0000-0000-0000-000000000002",
        "discussion_guide_question_id": "a1b2c3d4-0000-0000-0000-000000000002",
        "concept_id": null,
        "question": "Q2: How was your experience?",
        "answer": "Overall positive, but the onboarding could be smoother.",
        "question_id": "f1e2d3c4-0000-0000-0000-000000000002"
      }
    ],
    "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",
      "Asked for experience"
    ],
    "bullet_summary": [
      "Participant had a mostly positive experience.",
      "Onboarding flow was identified as an improvement area."
    ],
    "quality_score": 4,
    "tags": ["onboarding", "feedback", "improvements"],
    "summary": "Alice had a mostly positive experience but suggested onboarding improvements."
  }
]

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 (uses the analysis completion time when available).

progress · string

The completion progress of the response (e.g. "complete", "in_progress").

response_duration_seconds · number

The total duration of the response in seconds.

answers · object

Answers to all questions of the study.

Show Example Answers

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.

Show Response

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. Matches the id field from the Get Study Questions endpoint, enabling you to join answers with their question definitions.

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, prefixed with its number when available (e.g. "Q1: What is your age?").

answer · string

The answer to the question.

attributes · object

URL parameters that were passed to the study.

Show Example Attributes

id · string

An id that is passed to study eg. 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.

short_assistant_messages · string[]

Condensed assistant turns used to build compact transcript context.

bullet_summary · string[]

Concise bullet-point summary of the response.

quality_score · number

Numeric response quality score, typically on a 1-5 scale.

tags · string[]

Extracted keyword labels for the response.

tagline · string

Short one-line synthesis for the response.

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>'

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": {
      "Q1: What is your name?": "My name is John.",
      "Q2: How was your experience?": "It was great, very intuitive."
    },
    "answers_array": [
      {
        "answer_id": "f1e2d3c4-0000-0000-0000-000000000001",
        "discussion_guide_question_id": "a1b2c3d4-0000-0000-0000-000000000001",
        "concept_id": null,
        "question": "Q1: What is your name?",
        "answer": "My name is John.",
        "question_id": "f1e2d3c4-0000-0000-0000-000000000001"
      },
      {
        "answer_id": "f1e2d3c4-0000-0000-0000-000000000002",
        "discussion_guide_question_id": "a1b2c3d4-0000-0000-0000-000000000002",
        "concept_id": "b2c3d4e5-0000-0000-0000-000000000001",
        "question": "Q2: How was your experience?",
        "answer": "It was great, very intuitive.",
        "question_id": "f1e2d3c4-0000-0000-0000-000000000002"
      }
    ],
    "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",
      "Asked for experience"
    ],
    "bullet_summary": [
      "Participant reported a positive overall experience.",
      "Product was described as intuitive."
    ],
    "quality_score": 5,
    "tags": ["onboarding", "ux", "intuitive"],
    "tagline": "Positive experience with intuitive UX",
    "summary": "John had a positive experience and found the product intuitive."
  },
  {
    "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": {
      "Q1: What is your name?": "I'm Alice.",
      "Q2: How was your experience?": "Overall positive, but the onboarding could be smoother."
    },
    "answers_array": [
      {
        "answer_id": "f1e2d3c4-0000-0000-0000-000000000001",
        "discussion_guide_question_id": "a1b2c3d4-0000-0000-0000-000000000001",
        "concept_id": null,
        "question": "Q1: What is your name?",
        "answer": "I'm Alice.",
        "question_id": "f1e2d3c4-0000-0000-0000-000000000001"
      },
      {
        "answer_id": "f1e2d3c4-0000-0000-0000-000000000002",
        "discussion_guide_question_id": "a1b2c3d4-0000-0000-0000-000000000002",
        "concept_id": null,
        "question": "Q2: How was your experience?",
        "answer": "Overall positive, but the onboarding could be smoother.",
        "question_id": "f1e2d3c4-0000-0000-0000-000000000002"
      }
    ],
    "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",
      "Asked for experience"
    ],
    "bullet_summary": [
      "Participant had a mostly positive experience.",
      "Onboarding flow was identified as an improvement area."
    ],
    "quality_score": 4,
    "tags": ["onboarding", "feedback", "improvements"],
    "summary": "Alice had a mostly positive experience but suggested onboarding improvements."
  }
]