# Create Study
Source: https://docs.listenlabs.ai/api-v2/create-study
api-v2/openapi.yaml POST /api/public/v1/studies/create
Validate a study guide and create a draft study in your organization
# Get Single Response
Source: https://docs.listenlabs.ai/api-v2/get-response
api-v2/openapi.yaml GET /api/public/v1/responses/{linkId}/{responseId}
Retrieve one response's transcript, URL parameters, and summaries by UUID or readable ID
# Get Study Questions
Source: https://docs.listenlabs.ai/api-v2/get-study-questions
GET https://listenlabs.ai/api/public/v1/studies/{studyId}/questions
Get the participant-facing questions and concepts from a study's latest revision
Each question's `id` matches the `discussionGuideQuestionId` field in the
[response endpoints](/api-v2/list-responses), so you can join questions with
their corresponding answers and transcript rows — see the
[Data Map](/data-map).
### Path Parameters
The study's `id` or `linkId`, both returned by
[List Studies](/api-v2/list-studies). The legacy endpoint accepts only the
`linkId`.
### Response
The participant-facing questions from the study's latest editable revision.
Each question has a `type` field that determines its shape.
#### Common Fields
All question types share these base fields:
Unique identifier for the question. Matches the `discussionGuideQuestionId`
field in the response endpoints, enabling you to join questions with their
corresponding transcript rows and answers.
The question text shown to participants.
Whether this question is part of the screening section.
The question type. One of: `open_ended`, `file_upload`, `multiple_choice`,
`ranking`, `statement`, `matrix`, `max_diff`.
The human-readable question number (1-based) for display purposes.
An array of concept objects attached to this question (empty if the question
is not part of a concept test block).
Unique identifier for the concept. Referenced by `conceptId` on answers
and transcript rows.
The concept title.
The concept description.
An array of media attachments.
The media type. One of: `image`, `video`.
The file name of the media.
The URL of the media file.
An optional embed URL for the concept (e.g. a Figma or prototype link).
#### Multiple Choice Questions
`type: "multiple_choice"` questions additionally include:
Whether the participant can select multiple options.
The list of answer options.
#### Ranking Questions
`type: "ranking"` questions additionally include:
The list of items to rank.
#### Matrix Questions
`type: "matrix"` questions additionally include:
Whether multiple selections are allowed per row.
The row labels rated by the participant.
The column labels each row is rated across.
#### MaxDiff Questions
`type: "max_diff"` questions additionally include:
The items being compared.
What participants judge the items on (e.g. "importance").
How many items are shown per comparison screen.
#### Open-Ended, File Upload & Statement Questions
`type: "open_ended"`, `type: "file_upload"`, and `type: "statement"` questions
carry only the common fields.
### Errors
Errors share the [common envelope](/api-v2/overview#errors) (`error` + `code`):
| Status | Code | Meaning |
| ------ | ------------------------------------- | -------------------------------------------------------------- |
| `401` | `missing_api_key` / `invalid_api_key` | Missing or invalid API key. |
| `403` | `forbidden` | The key's user isn't a member of the key's organization. |
| `404` | `study_not_found` | Study not found in the key's organization. |
| `500` | `internal_error` | Internal error (details are logged server-side, not returned). |
```bash Example Request theme={null}
curl 'https://listenlabs.ai/api/public/v1/studies/9b2f1c3e-0000-0000-0000-000000000000/questions' \
-H 'x-api-key: '
```
```json Response theme={null}
{
"questions": [
{
"id": "a1b2c3d4-0000-0000-0000-000000000001",
"text": "How often do you drink coffee?",
"isScreener": true,
"questionNumber": 1,
"type": "multiple_choice",
"isMultiSelect": false,
"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,
"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",
"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",
"options": ["Price", "Origin", "Roast level", "Brand"],
"metric": "importance",
"itemsPerScreen": 4,
"concepts": []
}
]
}
```
# Launch Study
Source: https://docs.listenlabs.ai/api-v2/launch-study
api-v2/openapi.yaml POST /api/public/v1/studies/{studyId}/launch
Publish a draft study and get its self-recruit link
# Get Responses
Source: https://docs.listenlabs.ai/api-v2/list-responses
api-v2/openapi.yaml GET /api/public/v1/responses/{linkId}
List a study's responses with answers and summaries, paginated
# List Studies
Source: https://docs.listenlabs.ai/api-v2/list-studies
api-v2/openapi.yaml GET /api/public/v1/studies
List studies with titles, response counts, creators, and folder paths
## Study metadata
Each study includes `creator` and `folderPath` alongside its identifiers, title,
creation time, and completed response count. Both fields are always present but
may be `null`.
* `creator` contains the creator's `name` and `email`. Either nested value may
also be `null`.
* `folderPath` contains the study's folder path as an array of strings.
# List Wallets
Source: https://docs.listenlabs.ai/api-v2/list-wallets
api-v2/openapi.yaml GET /api/public/v1/wallets
List the wallets granted to your organization, with credit balances
# Listen Labs API
Source: https://docs.listenlabs.ai/api-v2/overview
Create, launch, and retrieve data from Listen Labs studies programmatically
The Listen Labs API lets you run studies entirely from code: define a study guide as JSON, create a draft, launch it to get a self-recruit link you can distribute to participants, and pull responses back out once interviews come in.
## Base URL
```
https://listenlabs.ai
```
## Authentication
All endpoints authenticate with an API key passed in the `x-api-key` header. The key is scoped to a single organization — studies are created in, and wallets are listed for, that organization.
```bash theme={null}
curl 'https://listenlabs.ai/api/public/v1/wallets' \
-H 'x-api-key: '
```
Admins and Supervisors can create API keys from the **Developer** section of their account page on Listen. See [Get API Access](/get-api-access) for details.
## Workflow
`POST /api/public/v1/studies/create` with a title and a [study guide](/api-v2/study-guide). The guide is validated up front; if it passes, you get back a draft study's `id` and `linkId`. Nothing is visible to participants yet — you can still review or edit the draft in the dashboard.
`GET /api/public/v1/wallets` lists the wallets granted to your organization with their recruitment and project credit balances. `walletId` can only be omitted at launch when your organization has exactly one wallet (it's auto-selected). If you have access to more than one, omitting it returns a `400` (`wallet_required`) — you must pass one from this list.
`POST /api/public/v1/studies/{studyId}/launch` publishes the draft and opens its self-recruit link. The response includes `selfRecruitLink` — share it with participants (or plug it into your own recruitment flow). Project responses bill to the launch wallet.
Once interviews come in, pull them with [Get Responses](/api-v2/list-responses) (`GET /api/public/v1/responses/{linkId}`) and drill into a single transcript with [Get Single Response](/api-v2/get-response). The `linkId` comes back from create/launch, or from [List Studies](/api-v2/list-studies). The [Data Map](/data-map) shows how these entities join together.
A complete create → launch example you can copy and run.
## Endpoints
| Endpoint | Description |
| ------------------------------------------------------------------------------- | ------------------------------------------------------------- |
| [`POST /api/public/v1/studies/create`](/api-v2/create-study) | Validate a study guide and create a draft study |
| [`POST /api/public/v1/studies/{studyId}/launch`](/api-v2/launch-study) | Publish a draft and return the self-recruit link |
| [`GET /api/public/v1/wallets`](/api-v2/list-wallets) | List the organization's wallets with balances |
| [`GET /api/public/v1/studies`](/api-v2/list-studies) | List studies with response counts, creators, and folder paths |
| [`GET /api/public/v1/studies/{studyId}/questions`](/api-v2/get-study-questions) | Get a study's questions and concepts |
| [`GET /api/public/v1/responses/{linkId}`](/api-v2/list-responses) | List all responses for a study |
| [`GET /api/public/v1/responses/{linkId}/{responseId}`](/api-v2/get-response) | Retrieve a single response |
## Errors
Every error response from the `/api/public/v1/*` endpoints shares one JSON envelope:
* `error` — a human-readable message. Useful for logs, but it may change; **don't** branch on it.
* `code` — a stable, machine-readable identifier. **Branch on this.**
* `issues` — present only on `400` schema failures (`code: invalid_request_body`): an array of per-field violations, each with a `path` and `message`.
```json 400 Schema violation theme={null}
{
"error": "Invalid request body",
"code": "invalid_request_body",
"issues": [
{
"code": "invalid_type",
"expected": "string",
"received": "undefined",
"path": ["title"],
"message": "Required"
}
]
}
```
```json 400 Invalid study guide theme={null}
{
"error": "Invalid study guide: conditional references unknown item externalId 'q2'",
"code": "invalid_study_guide"
}
```
### Error codes
| Status | Code | Meaning |
| ------ | -------------------------- | ------------------------------------------------------------------------------------- |
| `400` | `invalid_json` | Request body isn't valid JSON. |
| `400` | `invalid_request_body` | Body failed schema validation. See `issues` for per-field details. |
| `400` | `invalid_study_guide` | The study guide broke a cross-field rule (create only). |
| `400` | `wallet_required` | The organization has multiple wallets and `walletId` was omitted (launch only). |
| `400` | `insufficient_credits` | The wallet can't fund the launch — insufficient balance or grant limit (launch only). |
| `400` | `bad_request` | A query or path parameter is invalid (response endpoints only). |
| `401` | `missing_api_key` | No `x-api-key` header. |
| `401` | `invalid_api_key` | The API key is invalid. |
| `403` | `forbidden` | The key's user isn't a member of the key's organization. |
| `403` | `launch_permission_denied` | The key's user lacks permission to launch this study. |
| `403` | `wallet_access_denied` | No access to the specified wallet. |
| `404` | `study_not_found` | Study not found in the key's organization. |
| `404` | `response_not_found` | Response not found in the study (get response only). |
| `409` | `concurrent_modification` | The draft was modified concurrently; retry (create only). |
| `409` | `study_busy` | An update is in flight; retry after a moment (launch only). |
| `409` | `conflict` | The publish raced a concurrent edit; refresh and retry (launch only). |
| `500` | `internal_error` | Internal error. Details are logged server-side, not returned. |
Beyond field-level validation, the server enforces cross-field rules on the study guide (screening block placement, `minSelect`/`maxSelect` coupling, unique `externalId`s, reference resolution, `exclusiveOption` placement) and returns violations as `400` responses (`code: invalid_study_guide`). The full list is in the [Study Guide Reference](/api-v2/study-guide#validation-rules).
# Quickstart: Create & Launch a Study
Source: https://docs.listenlabs.ai/api-v2/quickstart
Go from JSON to a live self-recruit link in three requests
This walkthrough creates a study with a screener, an interview section, and conditional logic — then launches it and gets a link you can send to participants.
You'll need an API key (see [Get API Access](/get-api-access)). The key is scoped to one organization; the study is created there.
## 1. Create a draft study
`POST /api/public/v1/studies/create` takes the study definition and validates it. Note the `externalId` on the multiple choice question — the later open-ended question references it in a conditional.
```bash Request theme={null}
curl -X POST 'https://listenlabs.ai/api/public/v1/studies/create' \
-H 'x-api-key: ' \
-H 'Content-Type: application/json' \
-d '{
"title": "Coffee habits — API demo",
"externalTitle": "A short interview about your coffee routine",
"background": "We are a specialty coffee brand exploring how people choose what to buy.",
"studyGoal": "Understand what drives brand switching among regular coffee drinkers.",
"config": {
"interviewMode": "audio_text",
"questionLanguage": "en"
},
"welcomeMessage": {
"title": "Thanks for joining!",
"message": "This interview takes about 10 minutes. There are no wrong answers."
},
"closingMessage": "That is all — thank you for your time!",
"studyGuide": [
{
"type": "screening",
"title": "Screener",
"items": [
{
"type": "multiple_choice",
"text": "How often do you drink coffee?",
"options": [
{ "text": "Every day", "status": "approve" },
{ "text": "A few times a week", "status": "approve" },
{ "text": "Rarely or never", "status": "reject" }
]
}
]
},
{
"type": "flat",
"title": "Interview",
"items": [
{
"externalId": "purchase-channels",
"type": "multiple_choice",
"text": "Where do you usually buy coffee?",
"multiSelect": true,
"options": [
{ "externalId": "opt-cafe", "text": "Cafés" },
{ "externalId": "opt-grocery", "text": "Grocery stores" },
{ "externalId": "opt-online", "text": "Online" },
{ "text": "Somewhere else", "exclusiveOption": true }
]
},
{
"type": "open_ended",
"text": "What do you like about buying coffee online?",
"followUp": "medium",
"conditional": {
"operator": "and",
"criteria": [
{
"type": "selectedTemplateOptions",
"questionId": "purchase-channels",
"matchingCriteria": "mustSelect",
"choices": ["opt-online"]
}
]
}
},
{
"type": "open_ended",
"text": "Tell me about the last time you tried a new coffee brand.",
"followUp": "heavy"
}
]
}
]
}'
```
```json Response (201) theme={null}
{
"id": "9b2f1c3e-0000-0000-0000-000000000000",
"linkId": "coffee-habits-api-demo",
"status": "draft"
}
```
The study is now a **draft** — participants can't see it yet, and you can review or tweak it in the dashboard before launching. If validation fails, you get a `400` whose `code` tells you what went wrong (`invalid_request_body` includes an `issues` array pointing at the offending fields; `invalid_study_guide` flags a broken cross-field rule). Branch on `code`, not on the human-readable `error` text.
## 2. Find your wallet
Launching bills project responses to a wallet. `walletId` can only be omitted when your organization has exactly one wallet — launch then auto-selects it. With multiple wallets you must pass one explicitly, so list them and pick:
```bash Request theme={null}
curl 'https://listenlabs.ai/api/public/v1/wallets' \
-H 'x-api-key: '
```
```json Response (200) theme={null}
{
"wallets": [
{
"walletId": "5e8a7d40-0000-0000-0000-000000000000",
"name": "Research team",
"recruitmentCreditBalance": { "balance": 480, "usage": 20 },
"projectCreditBalance": { "balance": 950, "usage": 50 }
}
]
}
```
`usage` includes active holds.
## 3. Launch
The path takes the study's `id` from step 1 — the `linkId` is not accepted here.
```bash Request theme={null}
curl -X POST 'https://listenlabs.ai/api/public/v1/studies/9b2f1c3e-0000-0000-0000-000000000000/launch' \
-H 'x-api-key: ' \
-H 'Content-Type: application/json' \
-d '{ "walletId": "5e8a7d40-0000-0000-0000-000000000000" }'
```
```json Response (200) theme={null}
{
"id": "9b2f1c3e-0000-0000-0000-000000000000",
"linkId": "coffee-habits-api-demo",
"selfRecruitLink": "https://listenlabs.ai/s/coffee-habits-api-demo",
"status": "live",
"wallet": {
"walletId": "5e8a7d40-0000-0000-0000-000000000000",
"name": "Research team",
"recruitmentCreditBalance": { "balance": 480, "usage": 20 },
"projectCreditBalance": { "balance": 950, "usage": 50 }
}
}
```
The study is live. Share `selfRecruitLink` with participants — you can also append URL parameters (e.g. `?segment=pro`) and route on them with [`searchParam` conditionals](/api-v2/study-guide#conditional-logic) or read them back later from each response's `urlParams`.
If you omit the body and your organization has multiple wallets, launch returns `400` with `code: wallet_required` asking for an explicit `walletId`. A `409` (`code: study_busy` or `conflict`) means the study is mid-publish — retry after a moment.
## 4. Collect the results
Once responses come in, pull them with the data endpoints using the `linkId` (the study's `id` is accepted too):
```bash theme={null}
curl 'https://listenlabs.ai/api/public/v1/responses/coffee-habits-api-demo' \
-H 'x-api-key: '
```
All block and question types, conditionals, carry-forward, and validation rules.
Retrieve transcripts, answers, and summaries for a launched study.
# Study Guide Reference
Source: https://docs.listenlabs.ai/api-v2/study-guide
How to structure the studyGuide payload: blocks, question types, screening, concepts, conditional logic, and carry-forward
The `studyGuide` field of [Create Study](/api-v2/create-study) defines everything participants see: the questions, their order, screening, concept testing, and routing logic. It's an array of **blocks**, and each block contains one or more **items** (questions).
```json Minimal study theme={null}
{
"title": "Coffee habits interview",
"studyGuide": [
{
"type": "flat",
"title": "Main questions",
"items": [
{ "type": "open_ended", "text": "Walk me through your morning coffee routine." }
]
}
]
}
```
## Top-level request fields
Internal study title (shown in the dashboard).
Participant-facing title. Falls back to `title` when omitted.
Background context for the AI interviewer — what the study is about and who you're talking to.
What you want to learn. Helps the AI interviewer probe in the right direction.
Interview mode, languages, and platform targeting. See [Config](#config).
`{ "title": "...", "message": "..." }` shown to participants before the interview starts.
Message shown when the interview ends.
The blocks described below. At least one.
## Config
One of `text`, `audio`, `audio_text`, `audio_screen`, `video`, `video_screen`.
Language code the questions are written in (e.g. `en`, `de`, `fr`, `es`, `zh-TW`, `en-medical`). See the [complete language list](/setup-to-launch/languages-complete-list).
Translation target codes participants can switch to. `null` or omitted = English only.
Restrict which devices can take the study: any of `ios`, `android`, `desktop`.
```json Example config theme={null}
{
"config": {
"interviewMode": "audio_text",
"questionLanguage": "en",
"availableLanguages": ["en", "de", "fr"],
"targetPlatforms": ["desktop"]
}
}
```
## Blocks
Every block has a `type`, a `title`, and an `items` array (at least one item).
| Type | Purpose |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `flat` | A plain sequence of questions. |
| `screening` | Qualifies participants before the interview. At most one, and it must be the **first** block. |
| `concept` | Shows each participant one or more concepts (stimuli) and asks the block's questions about them. Requires `conceptSamplingConfig`. |
### Screening blocks
Screening blocks may contain **only `multiple_choice` items**, and every option must carry a `status`:
* `approve` — selecting it qualifies the participant
* `reject` — selecting it screens the participant out
* `neutral` — doesn't affect qualification
```json Screening block theme={null}
{
"type": "screening",
"title": "Screener",
"items": [
{
"externalId": "coffee-frequency",
"type": "multiple_choice",
"text": "How often do you drink coffee?",
"options": [
{ "externalId": "opt-daily", "text": "Every day", "status": "approve" },
{ "text": "A few times a week", "status": "approve" },
{ "text": "Rarely or never", "status": "reject" }
]
}
]
}
```
Outside screening blocks, `status` must be `null` or omitted.
### Concept blocks
Concept blocks show stimuli — product ideas, ads, prototypes — and ask the block's items about each one. They require a `conceptSamplingConfig` with at least one concept; other block types must omit it.
Each concept has a `nickname` (internal label) and `content`: a participant-facing `title`, optional `description`, optional `media` (images/videos), and an optional `embed` (e.g. a Figma prototype URL).
How many concepts each participant sees, randomly sampled. `null` = every participant sees all concepts.
Each concept can also carry a [`conditional`](#conditional-logic), so it's only shown to participants matching the criteria — e.g. gate each concept on a screener answer. `selectedTemplateOptions` criteria on a concept must reference an item in a block **before** the concept block.
```json Concept block theme={null}
{
"type": "concept",
"title": "Packaging concepts",
"conceptSamplingConfig": {
"subsampleCount": 2,
"concepts": [
{
"nickname": "minimal",
"content": {
"title": "Minimal design",
"description": "Clean white packaging with a single accent color.",
"media": [
{ "name": "minimal.png", "url": "https://example.com/minimal.png", "type": "image" }
]
}
},
{
"nickname": "bold",
"content": {
"title": "Bold design",
"embed": { "url": "https://www.figma.com/proto/..." }
},
"conditional": {
"operator": "and",
"criteria": [
{
"type": "selectedTemplateOptions",
"questionId": "coffee-frequency",
"matchingCriteria": "mustSelect",
"choices": ["opt-daily"]
}
]
}
}
]
},
"items": [
{ "type": "open_ended", "text": "What's your first impression of this design?" }
]
}
```
## Question types
All items share a few common fields:
The question text.
One of `open_ended`, `multiple_choice`, `ranking`, `matrix`, `max_diff`, `statement`.
Stable identifier for the item, unique within the payload. Auto-generated when omitted — set it only when a [conditional](#conditional-logic) or [`carryForwardFrom`](#carry-forward) needs to reference this item.
Show this question only when the criteria match. See [Conditional logic](#conditional-logic).
Images or videos shown with the question: `{ "name", "url", "type": "image" | "video", "widthPercentage"?, "forceWatching"? }`. `forceWatching` requires the participant to finish the video before answering.
An embedded web page shown with the question: `{ "url", "proxyUrl"? }`.
### Open-ended
The AI interviewer asks the question conversationally and can probe with follow-ups.
Follow-up depth: `none`, `light`, `medium`, or `heavy`.
Extra instructions for the AI interviewer on how to probe this question.
`text`, `voice`, `screenRecording`, or `none`.
Lets the AI observe the participant's screen while they answer. Only applies when `preferredInput` is `screenRecording`.
```json Open-ended theme={null}
{
"type": "open_ended",
"text": "Tell me about the last time you switched coffee brands.",
"followUp": "medium",
"addInstructions": "Probe for what triggered the switch and what almost stopped them.",
"preferredInput": "voice"
}
```
### Multiple choice
Required unless `carryForwardFrom` is set. Each option: `{ "text", "externalId"?, "status"?, "exclusiveOption"? }`.
Allow selecting more than one option.
Bounds on how many options must be selected. Both must be set together (or both omitted), only valid when `multiSelect` is `true`, and `minSelect` ≤ `maxSelect`.
Adds an "Other" option with free-text input.
Shuffle option order per participant.
Keep the last option in place when randomizing (e.g. "None of the above").
`externalId` of an earlier multi-select multiple choice item; this question shows only the options the participant selected there. See [Carry-forward](#carry-forward).
An option with `exclusiveOption: true` clears and locks the other selections when picked (e.g. "None of the above"). It's only valid on the **final** option of a multi-select question.
```json Multiple choice theme={null}
{
"externalId": "brands-used",
"type": "multiple_choice",
"text": "Which coffee brands have you bought in the last 3 months?",
"multiSelect": true,
"minSelect": 1,
"maxSelect": 4,
"randomizeOptionOrder": true,
"pinnedFinalOption": true,
"options": [
{ "externalId": "opt-blue-bottle", "text": "Blue Bottle" },
{ "externalId": "opt-stumptown", "text": "Stumptown" },
{ "externalId": "opt-lavazza", "text": "Lavazza" },
{ "text": "None of the above", "exclusiveOption": true }
]
}
```
### Ranking
Participants order the options. Supports `randomizeOptionOrder` and `carryForwardFrom` (rank only the options selected in an earlier multi-select question).
```json Ranking theme={null}
{
"type": "ranking",
"text": "Rank these brands from most to least trusted.",
"carryForwardFrom": "brands-used"
}
```
### Matrix
A grid: each **row** is rated single-select across the **options** (columns).
```json Matrix theme={null}
{
"externalId": "satisfaction-matrix",
"type": "matrix",
"text": "How satisfied are you with each of the following?",
"options": [
{ "text": "Not satisfied" },
{ "text": "Somewhat satisfied" },
{ "text": "Very satisfied" }
],
"rows": [
{ "text": "Taste" },
{ "text": "Price" },
{ "text": "Availability" }
]
}
```
### MaxDiff
Best/worst scaling across at least two options. See [MaxDiff analysis](/insights-and-reports/max-diff-questions) for how results are reported.
The items being compared (minimum 2).
What participants judge the items on (e.g. "importance", "appeal").
How many items are shown per comparison screen.
```json MaxDiff theme={null}
{
"type": "max_diff",
"text": "Which of these matters most and least when choosing a coffee?",
"metric": "importance",
"itemsPerScreen": 4,
"options": [
{ "text": "Price" },
{ "text": "Origin" },
{ "text": "Roast level" },
{ "text": "Brand" },
{ "text": "Packaging" }
]
}
```
### Statement
Not a question — shows text (and optional media/embed) with a continue button. Use it for instructions or section intros.
Custom label for the continue button.
```json Statement theme={null}
{
"type": "statement",
"text": "Next, we'll show you a few packaging designs. There are no right or wrong answers.",
"continueButtonText": "Show me"
}
```
## Conditional logic
Any item — and any [concept](#concept-blocks) in a concept block — can carry a `conditional`: it's only shown when the criteria match. Criteria are combined with an `operator` (`and` / `or`).
```json Show only if they selected Blue Bottle theme={null}
{
"type": "open_ended",
"text": "What keeps you coming back to Blue Bottle?",
"conditional": {
"operator": "and",
"criteria": [
{
"type": "selectedTemplateOptions",
"questionId": "brands-used",
"matchingCriteria": "mustSelect",
"choices": ["opt-blue-bottle"]
}
]
}
}
```
Two criterion types:
**`selectedTemplateOptions`** — based on an answer to an earlier `multiple_choice` or `matrix` item.
`externalId` of an earlier `multiple_choice` or `matrix` item. For a conditional on a concept, the item must live in a block **before** the concept block.
`mustSelect` or `mustNotSelect`.
Option `externalId`s (falls back to option text). For a matrix source, these are the columns.
Required only for a matrix source: the exact row text the criterion applies to.
**`searchParam`** — based on a URL parameter passed into the study link.
The query parameter name, e.g. `segment` in `https://listenlabs.ai/s/abc123?segment=pro`.
The value it must equal.
See also [Conditional logic](/setup-to-launch/conditional-logic) for how this behaves in the interview.
## Carry-forward
`multiple_choice` and `ranking` items can set `carryForwardFrom` to the `externalId` of an **earlier multi-select multiple choice** item. The question then only shows (or ranks) the options the participant actually selected there — so you can ask "which have you used?" followed by "which of *those* do you prefer?". When `carryForwardFrom` is set, omit `options`; they're inherited from the source question.
## External IDs
`externalId`s are stable handles you assign to blocks, items, options, and concepts. They're optional everywhere — the server auto-generates them when omitted — but you must set one on any item that a `conditional` (`questionId`) or `carryForwardFrom` references. Block, item, and concept `externalId`s must be unique across the entire payload.
## Validation rules
Beyond field-level validation, the server enforces these cross-field rules, returning `400` with `code: invalid_study_guide` and a descriptive `error` message when violated:
* At most **one screening block**, and it must be the **first** block.
* Screening blocks may contain only `multiple_choice` items, and every option in them must carry a `status`; outside screening blocks, `status` must be null/omitted.
* Concept blocks require `conceptSamplingConfig` with at least one concept; other block types must omit it.
* `externalId`s must be unique across blocks, items, and concepts.
* `conditional.criteria[].questionId` and `carryForwardFrom` must reference the `externalId` of an **earlier** item (of the right type).
* A concept's `conditional` must reference an item in a block **before** the concept block.
* `minSelect`/`maxSelect` must both be set or both omitted, only when `multiSelect` is true, with `minSelect` ≤ `maxSelect`.
* `exclusiveOption` is only valid on the final option of a multi-select `multiple_choice` question.
# Data Map
Source: https://docs.listenlabs.ai/data-map
How the public API entities relate to each other and which fields to use as join keys.
## Join Keys
| From | To | Join field | Notes |
| -------- | ------------- | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| Study | Response | `linkId` | Path param in `GET /api/public/v1/responses/{linkId}`. Accepts the study's `linkId` or its UUID `id`. Single response returns `linkId`. |
| Study | Question | `id` | Path param in `GET /api/public/v1/studies/{studyId}/questions`. Accepts the study's UUID `id` or its `linkId`. |
| Question | Answer | `discussionGuideQuestionId` | `Question.id` = `Answer.discussionGuideQuestionId` |
| Question | TranscriptRow | `discussionGuideQuestionId` | `Question.id` = `TranscriptRow.discussionGuideQuestionId` |
| Answer | TranscriptRow | `answerId` | One answer can have multiple transcript rows (follow-ups where `isFollowUp: true`). |
| Question | Concept | `concepts` | Array on the Question object. `conceptId` on Answer/TranscriptRow links to `Concept.id`. Empty when the question has no concepts. |
## Entity Fields
### Study
Returned by [List Studies](/api-v2/list-studies).
| Field | Type | Description |
| --------------- | ----------------- | ------------------------------------------------------------------------------------------------- |
| `id` | uuid | Permanent study identifier — the path param for launch, also accepted for questions and responses |
| `linkId` | string | Editable URL slug — accepted by the questions and response endpoints |
| `title` | string | Study title |
| `responseCount` | number | Completed response count |
| `createdAt` | string | UTC timestamp |
| `creator` | object \| null | Study creator. Contains `name` and `email`, each of which may be null. |
| `folderPath` | string\[] \| null | Study folder path as an array of strings. |
### Response
Returned by [Get Responses](/api-v2/list-responses). Each response belongs to a study via `linkId`.
| Field | Type | Description |
| ------------------------- | ---------------- | -------------------------------------------------------------------------------------------- |
| `id` | uuid | Response identifier |
| `readableId` | number | Order within the study |
| `progress` | string | `"complete"`, `"screened_out"`, or `"in_progress"` |
| `responseDurationSeconds` | number | Total duration |
| `qualityScore` | number \| string | Quality rating |
| `answers` | object | Keyed by question text, plus a `"Summary"` key (e.g. `"Summary"`, `"Q1: What is your age?"`) |
| `answersArray` | Answer\[] | Structured answers, joinable to questions and transcript |
| `urlParams` | object | URL params passed into the study |
| `tags` | string\[] | Keywords |
| `tagline` | string \| null | One-line synthesis |
| `bulletSummary` | string\[] | Bullet-point summary |
| `shortTranscript` | string \| null | Whole conversation with assistant messages shortened to a few words |
| `shortAssistantMessages` | string\[] | Condensed assistant turns (optional) |
| `otherRemarks` | string | Additional remarks (optional) |
| `personas` | string | Persona classification (optional) |
| `createdAt` | string | UTC timestamp |
| `updatedAt` | string | UTC timestamp |
### Answer
Nested inside `Response.answersArray`.
| Field | Type | Description |
| --------------------------- | -------------- | ------------------------------------------------------------------------------------------ |
| `answerId` | string | **Join key** — matches `TranscriptRow.answerId` |
| `discussionGuideQuestionId` | string \| null | **Join key** — matches `Question.id`. Null when the answer isn't tied to a guide question. |
| `conceptId` | string \| null | Links to `Concept.id` when the question involves concept testing |
| `question` | string | Question text |
| `answer` | string | Answer text |
### TranscriptRow
Returned by [Get Single Response](/api-v2/get-response) inside the `transcript` array.
| Field | Type | Description |
| --------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------- |
| `moderator` | string | Assistant/moderator text |
| `user` | string | Participant text |
| `discussionGuideQuestionId` | string \| null | **Join key** — matches `Question.id`. Null for non-question rows (e.g. intro). |
| `answerId` | string \| null | **Join key** — matches `Answer.answerId`. Null for non-question rows (e.g. intro). |
| `conceptId` | string \| null | Links to `Concept.id` |
| `responseIndex` | number | Zero-based row index |
| `isFollowUp` | boolean | `true` when this row is a follow-up to the same question as the previous row |
| `audio` | string \| null | Signed URL (\~1 hour validity) |
| `video` | object \| null | Camera recording — contains `streamUrl` (HLS) and `mp4Url` |
| `screenVideo` | object \| null | Screen recording (when the study captured the participant's screen) — contains `streamUrl` (HLS) and `mp4Url` |
### Question
Returned by [Get Study Questions](/api-v2/get-study-questions).
| Field | Type | Description |
| -------------------------- | -------------- | -------------------------------------------------------------------------------------------- |
| `id` | string | **Join key** — referenced as `discussionGuideQuestionId` on answers and transcript rows |
| `text` | string | Question text shown to participants |
| `type` | string | `open_ended`, `file_upload`, `multiple_choice`, `ranking`, `statement`, `matrix`, `max_diff` |
| `questionNumber` | number | Display order |
| `isScreener` | boolean | Whether this is a screener question |
| `options` | string\[] | Choices (for `multiple_choice`, `ranking`, and `max_diff` types) |
| `isMultiSelect` | boolean | Whether multiple selections are allowed (`multiple_choice` and `matrix` only) |
| `rows`, `columns` | string\[] | Matrix rows and columns (`matrix` only) |
| `metric`, `itemsPerScreen` | string, number | MaxDiff metric and items shown per screen (`max_diff` only) |
| `concepts` | Concept\[] | Concept definitions attached to this question |
### Concept
Nested inside `Question.concepts`.
| Field | Type | Description |
| ------------- | -------------- | ----------------------------------------------------- |
| `id` | string | Referenced by `conceptId` on Answer and TranscriptRow |
| `title` | string | Concept title |
| `description` | string | Concept description |
| `media` | Media\[] | Attached images/videos (`type`, `name`, `url`) |
| `embedUrl` | string \| null | External embed (e.g. Figma link) |
## Traversal Examples
### Get all answers for a study, grouped by question
1. `GET /api/public/v1/studies` — find the study's `id` and `linkId`
2. `GET /api/public/v1/studies/{studyId}/questions` — get all questions (using the `id`)
3. `GET /api/public/v1/responses/{linkId}` — get all responses
4. Join each `answersArray[]` item to its question using `discussionGuideQuestionId` = `Question.id`
### Match transcript audio/video to specific questions
1. `GET /api/public/v1/responses/{linkId}/{responseId}` — get the full transcript
2. `GET /api/public/v1/studies/{studyId}/questions` — get question definitions
3. Each transcript row's `discussionGuideQuestionId` tells you which question it belongs to
4. Use `audio`, `video`, and `screenVideo` fields on the transcript row to access the media for that exchange
### Group transcript rows by answer (including follow-ups)
1. `GET /api/public/v1/responses/{linkId}/{responseId}` — get the full transcript
2. Group transcript rows by `answerId` — rows sharing the same `answerId` belong to the same answer, with follow-ups marked by `isFollowUp: true`
3. Cross-reference with `answersArray` from the list endpoint using the same `answerId` to get the extracted answer text
# Authentication
Source: https://docs.listenlabs.ai/get-api-access
## API key
1. Go to your account page on Listen and open the **Developer** section. API keys can be created by Admins and Supervisors.
2. Create an API key.
3. Use it in your request in the `x-api-key` header.
```
'x-api-key': 'abc123....'
```
Each API key is scoped to a single organization. It works with all [versioned API endpoints](/api-v2/overview) (`/api/public/v1/...`) — studies, questions, wallets, and responses — as well as the legacy unversioned data endpoints (`/responses`, `/list_surveys`, questions).
# Welcome to Listen Labs
Source: https://docs.listenlabs.ai/get-started/index
Listen Labs is an AI-powered research platform.
Start with a business question. Listen handles the rest.
> From study design and recruitment to complex analysis workflows. Testing new product concepts or testing new markets. Listen is your trusted research partner that will deliver insights in hours instead of weeks.
This is your comprehensive guide to the Listen platform, covering everything you need to get started and launch your first study.
If you'd rather see it in action first, watch the video below where Camille, our Head of Insights Strategy, walks you through the platform in depth.
## Quick Start
Use Listen's AI-powered study builder to build a draft of your guide in minutes. Learn more about study set-up and what studies and question types we support.
Use Listen's built-in panel of 30M+ participants share your own link, or combine both. Learn more about launching and fielding studies.
How to leverage Listen to instantly get insights. Learn more about our reporting features, custom highlight reels, and slide deck generation.
Find out what we are building! Learn more about new features like Research Agent, emotional intellegence, and Mission Control.
***
## How It Works
**1. Co-Design Your Approach**
Click **New Study** from the dashboard to begin. Provide project background, company information, study objectives, and hypotheses. If you already have a discussion guide, upload it directly and the AI will intelligently parse it. Our AI helps you go from idea to implemented discussion guide in seconds.
**2. Recruit Your Audience**
Choose your recruitment method — Listen's built-in panel, a direct link for your own participants, or both. Set a response limit and click **Launch**. If you want, Listen can find and qualifies participants from our global network of 30M+ people.
**3. Moderate Interviews**
Listen conducts a video conversation and asks dynamic follow up questions. You can give the AI as much context as you want to help turn it into a subject matter expert in your field in minutes. Learn more about best practices here.
**4. Analyze & Deliver Results**
Our AI reviews all interviews and helps you turn findings into deliverables. Using Listen's Research Agent you can generate custom highlight reels, slide decks, executive summaries, and charts. You can also leverage our tools to cut and segment your data as granualarly as possible.
**5. Compound Your Knowledge**
Each study grows your knowledge base, so you can focus on net-new insights for your team. You can also leverage Listen's [Mission Control.](/insights-and-reports/mission-control)
***
## Key Features
**AI-powered study design:** Describe your goals and Listen drafts objectives, questions, and probing context. Listen's auto-QA features proactively flags issues before launch.
**Research Agent**: An AI assistant that turns findings into deliverables on command. Users can say things like "create slides summarizing the main findings" or "build a breakdown by segment" and it generates decks, memos, reports, charts, and highlight reels — in your branded template.
[**Mission Control**](/insights-and-reports/mission-control): A cross-study knowledge base that compounds over time. Ask questions across your entire research library, track trends over time, and get cited answers in seconds.
[**Emotional Intelligence**](/insights-and-reports/emotional-understanding): Multi-modal emotion detection that analyzes voice tone, facial expressions, and word choice together across 50+ languages. Built on Ekman's 6 core emotions plus UX-specific ones like confusion and frustration. Every emotion links to an exact timestamp and verbatim quote.
**Quality Guard**: Real-time fraud detection analyzing voice patterns, response depth, tab-switching, copy-paste, contradictions, and repeat respondents. Every response gets a quality score, and low-quality ones are removed and replaced at no cost.
**Listen Pulse**: Always-on continuous research that analyzes tens of thousands of responses 24/7 and surfaces how trends shift over time. The new era of qualitative tracking.
***
## Need Help?
**Support**: Email us at [support@listenlabs.ai](mailto:support@listenlabs.ai) for account, billing, or technical questions.
**Documentation**: Explore comprehensive guides, walk-thrus, and best practices throughout this document.
# Frequently Asked Questions
Source: https://docs.listenlabs.ai/get-started/studies-overview
Common questions about study setup, recruitment, analysis, video, languages, and account management
Answers to the most common questions about using Listen Labs as your AI-powered market researcher.
## Study Setup & Publishing
**How do I publish a study?**
Click **Review & Launch** in the top-right of the edit page. If the button is disabled, your study is already up to date. Note: publishing does not launch your study to participants — to recruit people, go to the Recruit tab.
**Study status explained.**\
Active: The study is live and actively collecting responses.
Paused: Fielding has been temporarily halted. This can be triggered manually or automatically as a result of changes to the study design.
Draft: The study has been created but not yet launched.
Closed: Fielding has ended and the study is no longer accepting responses.
**My study keeps pausing automatically. Why?**
This usually happens when a response limit is reached, or when too many people are rejected due to quota limits or wrong screener answers. See the [debugging quotas guide](/setup-to-launch/quotas). To resume, click the ellipsis (...) on your study in the dashboard and select "Resume."
**Can I make changes to a study after it's launched?**
Yes — make changes and click "Publish & Exit" to update the live study. If you delete questions that already have responses, previous answers to those questions will be removed from analysis.
**How do I copy or duplicate a study?**
From the dashboard (top left home button), click the three dots (...) on any study card to copy or duplicate it.
## Recruitment & Credits
**Can I recruit from both our panel and self-recruit in the same study?**
Yes, there's no technical limitation. You can combine panel recruitment with your own recruitment methods in the same study.
**How do response limits work?**
When you set a response limit, the study automatically pauses once that number of complete responses is reached. You can increase limits and resume from the dashboard. Note that all started responses are allowed to finish, so you might end up with a few more responses than the limit.
***
## Preview & Testing
**How can I test my study from a participant's perspective?**
Go to Recruit tab → Share a Link → copy the preview link. Alternatively, use the "Open Preview" button in the editor (does not save historical answers).
**Can participants step away and resume later?**
Yes — when visiting the same interview link again (same browser/device), progress is saved and they can continue where they left off.
***
## Responses & Data Management
**How do I hide or delete bad responses?**
In the Responses tab, select responses and click "Hide" at the bottom. After hiding, click "Update now" in the Analysis tab to refresh summaries without those responses.
**How can I see why respondents were screened out?**
In the Responses tab, clear the "complete" filter and switch to "screened out responses" using the top left dropdown. You'll see the screen out reason for each response.
***
## Analysis & Reports
**Can I export the graphs from the analysis page?**
Yes — use the download/copy buttons in the upper right corner of each chart in the Report or Details tab.
**Can I filter the analysis to show only completed responses?**
Yes — go to Responses tab, hide all incomplete responses, then click "Update" at the top of the Analysis page to regenerate with only complete responses.
**Can I analyze only a specific segment or quota group?**
You can create Segments and filter the analysis, or use the Chat function to ask questions about specific segments. Learn more about [using segments](/insights-and-reports/building-segments).
**How do I create segments for post-field analysis?**
Create Segments based on any multiple-choice question in the Analysis / Report tab at the top right. Advanced Segments can combine multiple questions or URL parameters.
**How do I update the analysis with new responses?**
Your Report and Details tabs continually update as new responses roll in.
**Can I get charts with percentages instead of respondent counts?**
On the Details page, click the options in the top right of any chart to switch to percentages. This isn't available in automatic PowerPoint generation.
**How can I upload and analyze answers to open-ended survey questions?**
On the dashboard, click "Analyze Survey" to analyze survey data collected externally. Uploading full unstructured interview transcripts is not currently supported.
***
## Quotas & Targeting
**Can I edit quotas after my study is launched?**
Yes, but changing quota definitions will reset all quotas and require reconfiguration. The system will recalculate how responses fall into new segments.
**Do quotas stop the study immediately when limits are reached?**
No — quotas are only checked after the complete screener is finished. Respondents must complete all screener questions before being terminated due to quota limits.
**Can I use URL parameters for quotas and conditional logic?**
Yes — if you configure URL parameters in the study setup, they'll appear as options in conditional logic dropdowns of advanced quotas.
***
## Concepts & Media
**Why isn't concept media showing in my preview?**
Check that "Show concept media" is enabled in the advanced settings of your concept questions. This should be on by default if you have media uploaded.
**Can I add images, videos, website URLs, or Figma prototypes as stimulus?**
Yes — in the manual (non-chat) editor, you can upload media for individual questions in the advanced settings, or add to a concept test. For videos, we support mp4 format.
***
## Video & Screen Recording
**Can I download video clips?**
Yes. For individual responses, highlight a quote and reference it in the quotes section (left panel) in the Clips tab. For report clips, click the ellipsis and download directly. For highlight reels, finalize the video, open the share link, and download from there. Learn more about [video clips](/insights-and-reports/clips).
**Why doesn't screen sharing content appear in my highlight clips?**
Screen share content in highlights needs to be enabled per study. Contact [support@listenlabs.ai](mailto:support@listenlabs.ai) to enable this for your study.
**Can respondents share their entire screen or just browser tabs?**
Participants can choose either a specific application window or their entire screen. Single-tab sharing isn't available.
**Do you offer mobile screen recording?** Yes. We currently only offer it on iOS devices. Just toggle on screen recording in the settings in the Edit tab, and you should be set up.
***
## Languages & Localization
**How many languages does Listen support?**
**Can I see what the translated guide looks like?**
Take the interview using the preview link and switch languages via the language dropdown, or use the export feature in the Create tab to download translated guides. We currently support 90+ languages, and 40+ languages with voice moderation.
**Can I upload my own translations?**
Use the "translation guidance" feature in the Settings tab to provide context for specific terms or paste an entire translated guide. Learn more about [translations](/setup-to-launch/auto-translations).
***
## Data Export & Integration
**Can I export video transcripts / download raw responses?**
Yes — use "Export complete responses" in the Recruit tab to download zip files with original transcripts in their native languages (and English), the Responses table, or full interview videos.
**How do I import additional data into my study?**
At the bottom of the Analysis tab, use the "Import Data" function. Upload a CSV file with response IDs and additional data columns to match to existing responses.
***
## Technical Issues
**Why is my study showing different response counts in different places?**
The recruit page shows all responses (including partial and panel/self-recruited), while individual sections may show only completed responses. Hidden responses also affect counts.
**Why won't the platform record audio/video properly?**
Check browser permissions for microphone/camera access. Some participants may need to enable these manually or try a different browser. If issues persist, reach out to [support@listenlabs.ai](mailto:support@listenlabs.ai).
***
## Account & Organization Management
**How do I add team members to my workspace?**
Workspace admins can invite new members via email by selecting "Workspace" in the left panel and clicking "Invite Members." Editors cannot add other members — only admins have this permission. To add a team member to a singular project only, click **Invite** at the top right of your specific project. Learn more about workspace permissions.
**Can I rename my workspace?**
Yes — go to workspace settings in the left panel to change your workspace name.
**What's the difference between admin, researcher, and collaborator roles?**
Admins have full access including member management. Researchers can see all studies, and launch new studies. Collaborators have read-only acess to study results.
**How do I switch between personal and company accounts?**
Use the organization selector/dropdown at the top left of the platform page to switch between workspaces you have access to.
***
**Still have questions?** Reach out at [support@listenlabs.ai](mailto:support@listenlabs.ai) and we'll help you out!
# Building Segments
Source: https://docs.listenlabs.ai/insights-and-reports/building-segments
Split participants into groups and compare their responses side by side
Segments let you split your participant data into groups and compare their responses side by side — answering questions like "Do customers and non-customers feel differently about this?" or "How do US and UK participants compare?"
## What Are Segments?
A segment is any subgroup of participants defined by a shared characteristic. That characteristic can be a screener answer, a demographic attribute, a URL parameter, or any combination of these. Once you define your segments, Listen filters the analysis for each group and displays them in parallel so you can spot differences immediately.
## Creating Segments
To set up segments, go to the Analysis tab, click Segments in the filter panel, and click Add Segment. From there, define your criteria using any of the following:
* A screener question and its qualifying answer(s)
* A demographic attribute such as age range, country, or gender
* A URL parameter value (for example, `group=US`)
Give your segment a clear name — something like "Current Customers," "Ages 18–34," or "US Market" — and repeat the process for each comparison group you need.
## Using Segments in Analysis
Once defined, every view in the Details tab updates to show analysis side by side for each segment. You can compare theme frequency to see whether one group mentions a topic more than another, sentiment and emotional tone across groups, average ratings and quantitative scores broken down by segment, and verbatim quotes filtered to each group.
You can also ask Research Agent to run segment-level comparisons directly. Try prompts like "Compare responses between our US and UK segments" or "What are the top differences between customers and non-customers?"
## Common Use Cases
* **Market comparison** — Compare reactions across countries in a single study. Combine segments with Listen's translation features to analyze all markets together rather than running separate studies per country.
* **Customer vs. non-customer** — See whether familiarity with your product changes perceptions, expectations, or emotional reactions.
* **Demographic analysis** — Compare responses across age groups, genders, or income brackets to understand how different audiences experience the same content.
* **Concept assignment** — Compare how participants who saw Concept A responded versus those who saw Concept B, with statistical significance testing built in.
For multi-market studies, combine segments with Listen's translation features to analyze all markets in one study rather than running separate studies per country.
# Video Clips & Highlight Reels
Source: https://docs.listenlabs.ai/insights-and-reports/clips
Create, share, and download video clip reels to showcase the most impactful moments from your research
Video clips are short highlight reels pulled directly from your research interviews. They let you showcase impactful moments and powerful participant quotes, right from their source. You can create custom clip reels manually by selecting specific quotes, or let the AI generate reels based on your study themes and analysis.
### Pro Tips
* **Use clips for executive presentations**: A 30-second highlight reel is far more compelling in a meeting than reading a quote aloud. Build clips for your key findings before any stakeholder presentation.
* **Prompt the AI well**: Specify content and key topics. Mention areas to focus on or omit. "Compile a clip showcasing diverse perspectives on usability" works better than just "make a clip."
* **Rename clips immediately**: Give clips descriptive names as you create them so they're easy to find and share later.
* **Build a clip library**: Create targeted clips for different purposes — an executive summary reel, a usability problems reel, a positive moments reel — and grow them into a reusable library over time.
### Quick Reference
| Action | How To |
| --------------------------- | ---------------------------------------------------------------- |
| Create a custom clip | Open participant response → highlight quote → Save → Add to clip |
| Generate AI clip | Clips tab → + Create New Clip → name + AI prompt → Generate |
| Rename a clip | Open clip → click title text → edit |
| Reorder quotes in a clip | Open clip → drag and drop quotes |
| Remove a quote from clip | Open clip → click trash can icon next to quote |
| Share a clip | Open clip → Share → Share link with anyone → Copy link |
| Download full clip reel | Open clip → Download (renders, delivered by email link) |
| Download single quote video | Participant panel → download arrow next to the quote |
***
## Complete Written Guide
### Step 1: Access the Clips Tab
1. Open your study from the Listen Labs dashboard
2. Navigate to the **Analysis** tab
3. Click **Clips** in the analysis navigation
4. You'll see AI-generated reels based on your themes, plus any clips you've created manually
### Step 2: Create a Custom Video Clip Reel (Manual)
To build a clip reel from specific participant quotes:
1. Open a participant's **response panel**
2. **Highlight the text** of a quote you want to include
3. Click **Save**
![Screenshot2025 09 17at2 05 19PM]()
4. Choose to **add to an existing clip** or click **+ Add New Clip** to create a new one (give it a name)
5. Repeat for all the quotes you want to include
6. Find all saved clips in **Analysis → Clips**
If your study uses translations, you must highlight the quote in the **native language** to save it to a clip. Toggle to the native language at the top of the participant's response panel.
### Step 3: Generate a Video Clip Reel with AI
To have the system build a clip for you:
1. Click **+ Create New Clip** in the upper left of the Clips page
2. Enter a **Name** for your reference
3. Add an **AI Prompt** describing what you'd like the clip to include
**Example prompts:**
* "Summarize the key findings from the study in a clip."
* "Compile a clip showcasing diverse perspectives on usability."
* "Generate a clip summary of the study's conclusions."
4. Click **Generate** — the system scans transcripts and creates a highlight reel based on your prompt
**Prompting guidelines:**
* ✅ Specify content and key topics to focus on
* ✅ Mention areas to include or omit
* ❌ Can't change animations or visual effects
* ❌ Can't specify exact timestamps or clip durations
### Step 4: Edit and Manage Your Clips
**Rename a clip:** Open the clip, click on the title text, and type a more descriptive name.
**Reorder quotes:** Open a clip, then drag and drop the quotes into the order you prefer.
**Remove a quote:** Open the clip and click the **trash can icon** next to the quote you want to remove.
### Step 5: Share Your Clips
1. Open a clip
2. Click the **Share** button
3. Select **Share link with anyone**
4. Copy the link and send via email, Slack, or any channel
Recipients can view the clip without needing a Listen Labs account.
### Step 6: Download Your Clips
**Download a full clip reel:**
1. Open a clip
2. Click the **Download** button
3. Rendering may take a few minutes — you'll receive an **email with a download link** once it's ready
![Screenshot2025 09 17at1 13 46PM]()
**Download the video of a single participant quote:** Use the **download arrow** next to that quote in the participant response panel.
### What's New in Clips (January 2026)
* **Non-English translated captions** are now available in clip reels
* **Screen recordings** can be included in highlight reels (contact support to request)
* **Edit auto-generated tags** that are included per respondent
* **Move clips into different orders** within a reel
***
**Anything missing?** Let us know at [support@listenlabs.ai](mailto:support@listenlabs.ai) and we'll help you out!
# Emotional Intelligence
Source: https://docs.listenlabs.ai/insights-and-reports/emotional-intelligence
Emotional Intelligence is Listen's multi-modal analysis layer that detects emotion across voice, tone, language, and video, revealing how facial expressions and word choice together can tell a different story than text alone.
Built to industry standards, Emotional Intelligence incorporates Ekman's [six universal emotions](https://www.paulekman.com/universal-emotions/) framework and is benchmarked against MELD for state-of-the-art accuracy.
## How Emotional Intelligence Works
Emotional Intelligence is a multi-modal analysis system that processes three signal types simultaneously:
* **Vocal pitch and tone** — Changes in voice that signal excitement, hesitation, discomfort, or certainty.
* **Facial expressions** — Visual signals captured from video responses.
* **Word choice** — Semantic signals in the language participants use.
These signals combine into emotion scores grounded in Ekman's six core emotions (Anger, Disgust, Fear, Happiness, Sadness, and Suprise). The model is validated against academic benchmarks (CMU-MOSEI and MELD frameworks).
Emotional Understanding analyzes behavioral signals — vocal patterns, word choice, and observable expressions. It does not collect or analyze biometric data.
## Understanding the Emotional Views
Listen gives you several ways to explore emotional data across your study:
**Emotional Timeline** shows how a participant's emotional state changed throughout an interview. Peaks and valleys correspond to moments of strong positive or negative reaction — use these to pinpoint the exact moments that matter most.
**Emotion Mapping** tracks emotional states over the course of an interview, identifying moments of positive emotion, negative emotion, hesitation, surprise, and more, and maps them to specific interview questions or moments.
**Aggregate Emotion View** gives you a study-level look at the emotional distribution across all participants for a given question or topic, letting you see patterns across your full sample.
**Emotion-filtered transcript clips** let you jump directly to the moments where a specific emotion appeared, so you can watch and hear the context for yourself.
## What You Can Learn
### Creative and Ad Testing
Tapping into emotional nuance is especially valuable for evaluating creative work. You can identify which executions generated genuine excitement versus polite interest, pinpoint where in a video ad participants disengaged or showed confusion, and see which specific elements drove the strongest emotional response.
### Concept Testing
When testing concepts, emotional data reveals which idea generated the most authentic positive reaction. It also helps you distinguish whether a negative reaction was confusion (which is solvable) or genuine dislike (which is more serious). You can run side-by-side emotional comparisons across concepts and markets.
### Usability Testing
For usability work, Emotional Intelligence surfaces the exact moments where participants experienced friction or frustration. It also reveals where delight appeared in the user journey — moments you should reinforce — and exposes the gap between verbal satisfaction ratings and actual emotional signals.
## Tips for Working With Emotional Data
* **Focus on unexpected emotional moments.** Sudden shifts in emotion — from positive to negative or vice versa — often signal the most important insights. Investigate what triggered the shift.
* **Cross-reference with quotes.** Emotional signals are hypotheses, not conclusions. Always read the transcript around an emotional moment to understand its context before drawing conclusions.
* **Use emotional data for concept testing.** Emotional reactions to stimuli (ads, product concepts, packaging) are especially valuable because participants often can't articulate why something resonates or doesn't.
* **Compare emotional responses across segments.** Filter by demographic group or screener answer to see if different groups react differently to the same questions.
* **Focus on sustained signals.** Strong emotional indicators held for 3–5 seconds are more meaningful than brief micro-expressions.
# Report Tab & Executive Summary
Source: https://docs.listenlabs.ai/insights-and-reports/executive-summary
Generate topline findings and an AI executive summary of your study's key results
The Report tab gives you a topline view of your entire study's findings — informed by your study objectives and background information, and presented in a clean, shareable format. It's your go-to for a high-level executive summary before diving into the question-by-question depth of the Details tab.
### Key Concepts Explained
**Report Tab**: Provides topline findings and an executive summary informed by your study objectives and background information. Primarily quantitative-focused and presented at the total level. Also available for export and sharing externally.
**Executive Summary**: An AI-generated overview of your study that distills the most significant findings into a concise, stakeholder-ready format — covering key themes, notable findings, and insights grounded in your research objectives.
**Topline Findings**: High-level takeaways from your study, presented at the total level (not broken out by segment or question). Ideal for an initial read-out to leadership or clients.
### Pro Tips
* **Wait for sufficient data**: Generate your first report summary after at least 10–15 interviews are complete. Earlier summaries may miss important themes that emerge from a larger sample.
* **Use the Report tab as a starting point**: The executive summary is a powerful first draft. Review it, add your own context and expertise, and customize it for your specific audience.
* **Combine with the Details tab**: The Report tab gives you the big picture; the Details tab gives you depth on each question. Use them together for a complete story.
* **Share directly with stakeholders**: The report exports cleanly and is formatted for sharing with non-researcher audiences — perfect for executives or clients who want the headline findings.
### Quick Reference
**Report Tab sections:**
* Study overview and methodology
* Topline findings (total level, quantitative-focused)
* Executive summary of key themes
* QA information on data quality
* Export and external sharing option
***
## Complete Written Guide
### Step 1: Access the Report Tab
1. Open your completed (or active) study
2. Navigate to the **Analysis** tab
3. Click **Report**
4. You'll see topline findings and an executive summary generated from your study data
### Step 2: Review Topline Findings
The Report tab presents high-level findings at the total level:
* **Study overview**: Background on the research, study objectives, and sample profile
* **Topline findings**: The most significant quantitative insights from across your study, informed by your research objectives
* **Executive summary**: An AI-generated narrative covering the key themes and what they mean
* **QA information**: Data quality indicators to help you understand the completeness of the dataset
### Step 3: Verify Key Claims
For every major finding you plan to share:
1. Note any claims that seem surprising or require validation
2. Navigate to the **Details tab** to see the underlying question-by-question data
3. Click into specific responses in the **Responses tab** to verify the source quotes
4. Add your own context or caveats as needed before sharing
### Step 4: Export and Share
1. Click **Export** or **Share** in the Report tab toolbar
2. Choose your format:
* **PDF** for a formatted document ready to share externally
* **Export to document** for an editable version
* **Share link** to give external stakeholders view-only access without a Listen Labs login
You can regenerate the report at any time as more interviews complete. Each regeneration incorporates the latest interview data and may surface new or updated findings.
### Step 5: Move to the Details Tab for Depth
After reviewing the Report tab's high-level summary:
1. Navigate to the **Details** tab for a question-by-question deep dive
2. Download the auto-generated **PowerPoint deck** for immediate stakeholder use
3. Generate **custom reports** using a specific prompt to focus on particular themes or objectives
4. Use the right-hand navigation to explore analysis for each individual question
### Best Practices
**Before Sharing:**
* Review the Report tab summary and verify the key claims against underlying data
* Supplement the AI summary with your own research expertise and domain context
* Tailor the executive summary framing for your specific audience — executives need different framing than product teams
**After Sharing:**
* Be ready to direct stakeholders to specific questions in the Details tab if they want more depth
* Use the PowerPoint from the Details tab alongside the Report tab summary for a complete presentation package
***
**Anything missing?** Let us know at [support@listenlabs.ai](mailto:support@listenlabs.ai) and we'll help you out!
# MaxDiff Questions
Source: https://docs.listenlabs.ai/insights-and-reports/max-diff-questions
MaxDiff mimics real-world decision-making by forcing tradeoffs and identifying what people value most.
In a nutshell: MaxDiff reveals how customers prioritize a large set of options without overwhelming them to evaluate everything at once. The *index score* estimates how likely an option is to be chosen as “best” when compared against a random selection of competing options. Scores are normalized so that the average option equals 100. An option with an index score of 200 is expected to be chosen roughly twice as often as an option with a score of 100. We compute it using a state-of-the-art Hierarchical Bayes analysis.
Imagine you have 20 product feature ideas but only have the capacity to build three of them this quarter. Your first thought may be to ask respondents to rate each option on a 1 to 5 likert scale and pick the top three by average rating. While conceptually simple, the result will most likely be a large number of uninformative ties. Respondents tend to put most reasonable options at the top of the scale, especially in Western culture, where it is polite to agree.
To get something informative, we need to force respondents to make tough choices: We do not ask respondents *how much* they like each option; instead we ask them to rank options against each other. However, asking respondents rank 20 options at once is likely to overwhelm them. This is where MaxDiff comes in.
## How MaxDiff works
Instead of ranking all the options at once, your participants repeatedly select the *best* and *worst* option from random subsets of e.g. four options. Each selection in itself is simple for the respondent. But in aggregate, we can reconstruct how much they like each option relative to each other.
Let's go through this in an example. Suppose you want to know how people rank eight dessert options: Apple Pie, Chocolate Cake, Ice Cream, Cheesecake, Brownies, Donuts, Cupcakes, and Cookies. Participants will then see a series of six random subsets and select the best and worst option from that subset. For an exemplary participant, this may look as follows:
| Step | Options shown | Selection |
| ---- | ---------------------------------------------- | ------------------------------------- |
| 1 | Chocolate Cake, Ice Cream, Apple Pie, Donuts | Best: Chocolate Cake, Worst: Donuts |
| 2 | Chocolate Cake, Cheesecake, Brownies, Cupcakes | Best: Chocolate Cake, Worst: Cupcakes |
| 3 | Chocolate Cake, Cookies, Apple Pie, Donuts | Best: Chocolate Cake, Worst: Donuts |
| 4 | Ice Cream, Cheesecake, Brownies, Cookies | Best: Ice Cream, Worst: Cookies |
| 5 | Ice Cream, Cheesecake, Apple Pie, Cupcakes | Best: Ice Cream, Worst: Cupcakes |
| 6 | Brownies, Cookies, Apple Pie, Donuts | Best: Brownies, Worst: Donuts |
We may find a ranking consistent with the selections we observer, for example:
> Chocolate Cake > Ice Cream > Cheesecake > Brownies > Cookies > Apple Pie > Cupcakes > Donuts
Notice, however, that we cannot tell for sure whether this particular respondent prefers cheesecake to brownies or the other way around. The selections *indicate* the underlying preferences but do not uniquely *determine* them. Therefore, we infer how respondents rank each option through a *statistical model* that even uses similarities between responses to better estimate what each respondent thinks about each option.
## Inferring the underlying rankings
After observing all selections, we compute for each participant and option how likely they will like that option best on a random screen of other options. In the example above, the respondent chose Chocolate Cake as the best option three times. Therefore, we expect Chocolate Cake to perform pretty well against random competitors.
How much participants like an option is quantified through the so-called *index score*. It estimates for each option how likely a random participant is to select that option against a random subset of other options. The score is calibrated so that the average option has an index score of 100. If option A has double the index score of option B, the participant is twice as likely to like A best on a random subset than to like B best.
We estimate index scores with a state-of-the-art statistical model of how respondents selections on a screen: Hierarchical Bayes. This accounts for various factors such as:
* **Correlations between options:** Imagine the example above but with no general consensus. However, our model may find that respondents who like chocolate cake tend to also like brownies, and the respondent in question liked chocolate cake. Then, our model will infer that the respondent may prefer brownies.
* **The hierarchy between options:** If I know Johnny likes Donuts more than Cookies, and Brownies more than Donuts, then Johnny probably also likes Brownies more than Cookies, even if Johnny was never asked to pick between the two.
* **Correlations between respondents**: Imagine that for a particular respondent, we lack indicators on whether they like e.g. brownies or cookies better. If, however, the general consensus is that cookies are preferred to brownies, our model will infer that this respondent will probably follow the trend.
* **Accidental misclicks**: Sometimes, respondents make mistakes. Our model is robust to those. If, for example, a respondent consistently likes Chocolate Cake best but in one screen likes it worst, our model will infer that this was probably a misclick.
## What Should I use MaxDiff for?
MaxDiff shines whenever you need to prioritize among a long list of options. In the real world:
* Marketers cannot launch 10 campaigns at once
* Engineers cannot build the entire feature roadmap in one sprint
* Designers cannot highlight everything on prime real estate
Some exemplary use cases include:
* Prioritizing a feature roadmap into which new capabilities are most likely to 1) drive net new app downloads, or 2) encourage existing customers to re-up their subscription
* Prioritizing which messaging themes should be featured first on a LinkedIn campaign
* Prioritizing CMF design, guiding which color smart speaker to launch 1st, 2nd, and 3rd, and the impact each additional color has on your customer’s likelihood to purchase your speaker vs. a competitors
* Prioritizing which features belong in the free vs. pro vs. enterprise subscription tier. Placing the right features in free to attract new users, while placing the most valuable, potentially more niche features behind a paywall to maximize monetization
* Prioritize which customer frustrations and pain points generate the most angst and risk of churn, guiding engineering to focus on addressing the biggest risks
MaxDiff should be avoided when
* You need absolute scoring instead of relative rankings: Use matrix questions instead; MaxDiff only ranks options relative to each other.
* The number of options is small: For five or less options, a ranking question is more effective.
## How exactly do we compute these numbers?
We use an advanced statistical model, Hierarchical Bayes, to estimate a *utility score* $u_{i,j}$ for each respondent $i$ and option $j$. Higher utility scores indicate that respondents like an option better. Have a look at [this blog post](https://listenlabs.ai/blog/maxdiff-questions) for a detailed explanation.
There is one key idea for converting utility scores into interpretable numbers: Given a subset of options $S$ is available for selection on screen, the model sets the probability of selecting option $j \in S$ as the best option is modeled to be:
$$
p(i \text{ selects } j \text{ selected as best from }S)=\frac{e^{u_{i,j}}}{\sum_{j' \in S} e^{u_{i,j'}}}
$$
We zero-center the utilities by-respondent, i.e. for each respondent, the average item has a utility of zero. A standard metric is the **probability of choice** (POC). Given a design with $a$ **options per screen**, POC is the probability that respondent $i$ selects option $j$ as the best option against the remaining $a-1$ options where the remaining options are assumed to have a representative score of $0$, i.e. the average score. Given $e^0=1$, plugging this into the formula above yields:
$$
\text{POC}_{i,j}\equiv p(i \text{ selects } j \text{ as best vs representative options }) =\frac{e^{u_{i,j}}}{e^{u_{i,j}}+a-1}
$$
The POC of an option $j$ is defined as the average POC for that option over all respondents.
The **index score** rescales the POC by-respondent so that the average index score is 100, i.e.:
$\text{index score}_{i,j} = \frac{\text{POC}_{i,j}}{\text{avg}_{j'}(\text{POC}_{i,j'})} \cdot 100$
$\text{index score}_j = \text{avg}_i\left(\text{index score}_{i,j}\right)$
For **head-to-head** comparisons between two options A and B, we simply compute the selection probability restricted to the set $S=\{A,B\}$.
## Portfolio Analysis (TURF)
Imagine you do not just want to find the best option, but you have budget to implement a limited subset of options, e.g. you can implement up to three of the ten proposed features. Your first instinct might be to implement the top three features by index score. However, this may not be optimal for maximizing reach in your customer base. For example, imagine you implemented the best-ranked option. Continuing with the second-best-ranked option may no longer be optimal: The respondents who like the second-ranked option may already be satisfied because they like the first-ranked option that you just implemented. It is possible that e.g. the fourth-ranked option could reach an entire new set of customers, providing higher marginal return.
This is where Total Unduplicated Reach and Frequency (TURF) analysis comes in. The analysis broadly works in three steps:
1. **Define a threshold** for when an option is counted as *reaching* a customer. We support three options:
1. **Top population %**: Compute the $p$-th percentile of the utility matrix $u_{:,:}$: $u_{\text{cutoff}}(p) \equiv \text{percentile}(u_{:,:},p)$. A respondent $i$ counts as reached by an option $j$ iff $u_{i,j} \geq u_{\text{cutoff}(p)}$.
2. **Choice probability**: Each respondent counts as reached iff $\text{POC}_{i,j}$is at least the selected probability threshold.
3. **Top k**: A respondent is reached by an option iff it is in their top k options by utility score.
2. **Select a maximum portfolio size**. Pick how many options you can pursue in total.
3. **Let us find the options that maximize reach**.
# Research Agent
Source: https://docs.listenlabs.ai/insights-and-reports/personas
Your collaborative AI assistant for analysis, deliverables, and insight discovery
Research Agent is your collaborative AI assistant inside every study. With a single prompt, it can run analysis, generate deliverables, surface insights, and answer questions — all grounded in your actual participant responses.
You'll find Research Agent in the **Chat tab of your Analysis page.** Just start a conversation and ask for what you need.
## What Research Agent Can Do
Research Agent goes far beyond simple Q\&A. It can run segmented analysis and significance testing across your data, answer specific research questions with citations to exact participant quotes and timestamps, and surface unexpected findings or outlier opinions you might otherwise miss.
On the deliverables side, Research Agent can generate reports, memos, and slide decks tailored to your study goals. It builds custom charts and visualizations on demand, and can create highlight reels and video compilations pulled from your clip library. It can even pull in external context like industry benchmarks, competitor activity, and public data to enrich your analysis.
## Example Prompts
Not sure where to start? Here are some prompts to try:
* "Summarize the key findings from this study in a memo format."
* "Create a PowerPoint with main findings organized by our study goals."
* "What are the top 3 themes among participants under 35?"
* "Compare responses between our US and UK segments and flag significant differences."
* "Create a table of the 10 most compelling quotes about X."
* "What context from my previous studies is relevant to these findings?"
## What Research Agent Can Create
Research Agent can produce a range of ready-to-use deliverables directly from your conversation:
* **Presentations** — Slide decks structured around your study goals, with charts and supporting quotes baked in.
* **Reports** — Narrative memos that walk through findings organized by objective.
* **Data tables** — Custom breakdowns, segmentations, and comparisons formatted for easy sharing.
* **Highlight reels** — Video compilations organized around themes or specific questions you specify.
## Research Agent Across Studies
Research Agent isn't limited to the study you're currently viewing. It can reach across your entire research library, pulling from your organization's full history in Mission Control. Ask a question that benefits from past context and it will draw on relevant findings from previous studies automatically.
Research Agent works best when Study Objectives and Background Information are filled out thoroughly in Project Settings. The richer the context you provide, the more targeted its outputs.
# Workspace Presentation Templates
Source: https://docs.listenlabs.ai/insights-and-reports/presentation-templates
Generate Listen presentations in your own branding by configuring a workspace-level template
Listen can generate presentations using your own PowerPoint template, so every auto-generated presentation matches your company's fonts, colors, and slide layouts. Upload a template once at the workspace level and all future presentations will be built on top of it.
## How It Works
When you provide a `.pptx` template, Listen's presentation agent analyzes your deck: its theme, slide layouts, fonts, colors, and imagery. When generating a presentation, it decides for each slide whether to reuse one of your existing layouts or build a new slide from your theme, then fills in findings, quotes, charts, concept images, and highlight reels from your study. The agent reviews its own output and iterates until the deck matches your formatting.
## Choosing a Template
Any `.pptx` file can work as a template, but some make better starting points than others:
* **Your company's branded template** works best: the kind of deck your design team shares internally, with title slides, section dividers, content layouts, and theme colors already defined.
* **A past report or share-out deck** also works well. If your research team has a standard format for presenting findings, that deck is a great template. You don't need to remove the content; the agent uses it to understand your style.
Templates that are very bare (a single blank slide) or unusually complex can produce weaker output. That's why we recommend testing before you configure one for your whole workspace.
## Test Your Template First
Before setting a template at the workspace level, test it on a single study. Once configured, the template applies to all future presentations in your workspace, so it's worth confirming the output looks right first.
Pick a previously completed study (or one of our Demo studies) and open the Chat tab.
Upload your `.pptx` file to the chat and ask for something like: "Generate a presentation summarizing this study, based on the attached template."
Presentation generation generally takes 15 to 20 minutes, but can take up to an hour for more complex studies and presentations. Feel free to close the tab and come back.
Check that fonts, colors, layouts, and charts match your branding. If something looks off, adjust your template (see tips below) and test again, or reach out to us and we'll help troubleshoot.
## Configure Your Workspace Template
Once you're happy with the test output:
1. Go to your **Workspace** settings.
2. Find the **Presentation template** section.
3. Upload your `.pptx` file.
That's it. You can replace or delete the template from the same place at any time. Note that only workspace admins can manage the template.
## When the Template Applies
The workspace template applies to presentations generated from the Presentations view, but not to decks generated through chat. Chat always requires attaching the template file directly.
| How the presentation is generated | Uses your workspace template? |
| ----------------------------------------- | ------------------------------------------------------------------------------------------ |
| Auto-generated presentations | Yes, by default |
| Manually from **Details > Presentations** | Yes, by default. Uncheck **Use workspace template** to use Listen's default format instead |
| Through the study chat | No. Attach your `.pptx` to the chat and mention you want the presentation based on it |
## Tips for Better Results
* **Include a variety of layouts.** Title slides, section dividers, content slides with different arrangements, and slides with charts or imagery all give the agent more to work with.
* **Make sure your theme is set up.** Fonts and colors defined in the PowerPoint theme (rather than applied ad hoc to individual text boxes) carry over most reliably.
* **Keep brand assets in the deck.** Logos, icons, and imagery included in the template can be reused in generated slides.
If a generated deck doesn't look right, the fastest fix is usually the template itself: add a few more example layouts or clean up the theme, then re-test through chat before updating your workspace template.
Questions about Presentation Templates? Email [support@listenlabs.ai](mailto:support@listenlabs.ai).
# Question Analysis & Details Tab
Source: https://docs.listenlabs.ai/insights-and-reports/question-analysis
Explore question-by-question analysis, quantitative charts, and AI-generated summaries for your study
The Details tab in your Analysis section gives you a ready-to-present, question-by-question view of your research findings. Each question in your discussion guide gets its own deep-dive — with AI-generated summaries, quantitative breakdowns, segment comparisons, and video highlights. You can also download editable PowerPoints directly for stakeholder sharing.
### Key Concepts Explained
**Details Tab**: A question-by-question analysis view with visualized data and key findings. Organized by your discussion guide's core questions, this is where the bulk of your granular analysis lives.
**AI-Generated Summary**: For each open-ended question, the AI writes a summary of what participants said — synthesizing themes, representative quotes, and notable outliers.
**Quantitative Analysis**: A statistical breakdown of qualitative responses by themes — showing how many participants mentioned each concept or theme. Makes open-ended data feel more measurable.
**Segment Analysis**: Within each question's AI summary, a comparative section shows how different participant groups (segments) responded differently — with representative quotes per group.
**Outlier Detection**: The AI flags surprising statements that deviate from the main themes and may indicate emerging trends or edge cases worth investigating.
### Pro Tips
* **Download the PowerPoint**: The Details tab generates ready-to-present, editable PowerPoints with visualized data. Download these directly for immediate stakeholder sharing.
* **Generate custom reports**: Use the prompt feature to generate targeted decks with a specific focus area. Best practice: create multiple targeted decks, then combine the best slides.
* **Navigate by question**: Use the right-hand navigation to jump directly to the analysis for each core question from your discussion guide.
* **Set up Segments before running analysis**: If you plan to compare groups, define your segments first — the Segment Analysis section will appear automatically within each question's AI summary.
### Quick Reference
**For each question you'll see:**
* AI-generated summary of what participants said
* Quantitative theme breakdown (how many participants mentioned each theme)
* Segment Analysis (how different groups responded)
* Outlier Detection (surprising or atypical responses)
* Video Highlights (compilation clips with closed captioning)
**PowerPoint export options:**
* Download the default visualized deck
* Generate a custom report using a specific prompt
* Combine slides from multiple targeted decks
***
## Complete Written Guide
### Step 1: Access the Details Tab
1. Open your completed (or active) study
2. Navigate to the **Analysis** tab
3. Click **Details**
4. You'll see a full deck view of visualized data and key findings
### Step 2: Download the PowerPoint
1. The Details tab generates a ready-to-present, editable PowerPoint with visualized data
2. Click **Download** to export the deck directly
3. Use it immediately for stakeholder presentations — no reformatting needed
**Generate a custom report:**
1. Click the prompt field in the Details tab
2. Enter a specific focus area (e.g., "focus on pricing concerns and conversion barriers")
3. The system generates a targeted deck based on your criteria
4. Best practice: generate multiple targeted decks, then combine the best slides into a final deliverable
### Step 3: Navigate Question-by-Question
On the right-hand side of the Details tab, you'll find navigation for each of the core questions from your discussion guide. Click any question to jump to its analysis.
Within each question's view:
**AI-Generated Summary:**
A synthesis of what participants said — covering the main themes, how common they were, and representative quotes.
**Quantitative Analysis:**
A statistical breakdown of qualitative responses by themes, showing what percentage of participants mentioned each concept.
**Segment Analysis:**
If you've set up Segments, a Segment Analysis section appears automatically — comparing how different groups responded, with representative quotes per segment.
**Outlier Detection:**
The AI flags surprising statements that may indicate emerging trends — useful for surfacing things you might otherwise miss in a large dataset.
**Video Highlights:**
Compilation clips with closed captioning showing key participant responses for that question.
### Step 4: Use the Report Tab for Topline Findings
In addition to the Details tab, the **Report tab** provides:
* Topline findings informed by your study objectives and background information
* An executive summary of the overall study
* Primarily quantitative-focused and presented at the total level
* Available for export and external sharing
The Report tab is ideal for a high-level overview, while the Details tab is where you go for depth on individual questions.
Both the Report tab and Details tab can be shared externally. Use the export options to generate shareable PDFs or PowerPoints for stakeholders who don't have Listen Labs access.
***
**Anything missing?** Let us know at [support@listenlabs.ai](mailto:support@listenlabs.ai) and we'll help you out!
# Research Library
Source: https://docs.listenlabs.ai/insights-and-reports/research-library
Your cross-study intelligence hub — query everything you've ever learned from your customers
Research Library is Listen's cross-study intelligence hub — your organization's source of truth for everything you've ever learned from your customers. Instead of each study living in isolation, Research Library connects them into a growing, queryable knowledge base.
## What Is Research Library?
Research Library is a workspace-level view that aggregates findings, themes, and data from every study you've run. It lets you ask questions across your entire research history and get cited, traceable answers in seconds. Think of it as the collective memory of your research program — always available, always up to date.
You can access Research Library from the main navigation on your workspace homepage. It's workspace-level, meaning all studies contribute to it, subject to your access permissions.
## Cross-Study Queries
You interact with Research Library through the same natural language chat interface as Research Agent, but with access to your full research library rather than a single study. Ask a question and Research Library will search across every study, surface the relevant findings, and cite the specific studies, questions, and participant quotes that informed its answer.
Some example queries to get started:
* "What have we learned about checkout abandonment across all our studies?"
* "Summarize our recent studies into a slideshow for leadership."
* "What are the top recurring pain points across all our research this year?"
* "Find common threads between our US and European studies."
* "What were the most surprising findings from any study we've run?"
Every answer includes citations — links to the specific studies, questions, and participant quotes behind it — so you can always trace a finding back to its source.
## Tracking Trends Over Time
Research Library makes it possible to compare how customer sentiment, needs, and pain points have evolved across studies over time. Run the same study quarterly and use Research Library to surface how responses shift, turning one-off research into a longitudinal view of your customer.
## Building Institutional Knowledge
One of Research Library's most valuable roles is making research accessible across your organization. New team members can get up to speed on customer insights without reading every past report. Research findings become accessible across functions — product, marketing, strategy, and leadership can all query the same knowledge base. And your team stops re-discovering the same insights and can focus on net-new learning instead.
Research Library gets more powerful with every study you run. Consistent use builds a compounding knowledge advantage — each study makes every future study faster and more informed.
Questions about Research Library? Email [support@listenlabs.ai](mailto:support@listenlabs.ai).
# Appending External Data
Source: https://docs.listenlabs.ai/insights-and-reports/thematic-analysis
Enrich your Listen Labs study with external data sources for deeper segmentation and analysis
You can enrich your Listen Labs study by appending external data — such as CRM attributes, survey responses, or behavioral logs — and then use that data for segmentation, comparison, and analysis inside the platform. This lets you connect what participants say in Listen with what you already know about them from other sources.
### Key Concepts Explained
**Imported Data**: Additional attributes attached to participants by matching them to rows in an external .csv file using a shared identifier. Once imported, this data becomes available for charts, segments, and filtering.
**Match Identifier**: The unique value used to connect participants in Listen to rows in your .csv — such as a Listen ID, a URL parameter ID, or a panel-provided respondent ID. Every participant is matched row-by-row based on this identifier.
**Post-Import Segments**: After importing data, the imported fields become available as segment criteria — just like screener answers or URL parameters. Use them to create groups based on CRM attributes, survey answers, or other external data.
**Advanced Segments with Imported Data**: Imported fields can be combined with other attributes using AND/OR logic to create highly specific participant groups for comparison.
### Pro Tips
* **Plan ahead**: Decide what external data you'll want to segment on before launching your study. Design your URL parameters and respondent IDs so they match your external data sources.
* **Clean your .csv before uploading**: Remove extra spaces, ensure consistent casing, and verify that your matching identifier column is unique across rows.
* **Ensure your identifier is consistent**: If your matching identifier appears differently in Listen vs. your .csv (e.g., "#221" vs. "221"), the match will fail. Test with a small batch first.
* **Re-upload if needed**: You can re-import updated files — this replaces any previously uploaded .csv data, so you can correct errors or add new fields.
### Quick Reference
**What external data can you append?**
* CRM attributes (plan type, tenure, account size)
* Quantitative survey responses from another tool
* Typing tools or behavioral logs
* Any other structured data stored in a .csv
**What matching identifiers can you use?**
* Listen ID (e.g., #221)
* IDs passed via URL parameters
* Panel-provided respondent IDs
* Any other unique value present in both datasets
**After importing, your data appears in:**
* Bar charts at the bottom of the Details tab
* Segment builder (available as criteria)
* Responses table (as new columns)
***
## Complete Written Guide
### Step 1: Prepare Your .csv File
Before uploading, ensure your file is ready:
1. Include a **unique identifier column** that matches a value present in your Listen study (e.g., a respondent ID or URL parameter value)
2. Clean the file — remove extra spaces, ensure consistent casing, and check that the identifier is unique per row
3. Include any additional columns (CRM fields, survey answers, etc.) you want to bring into Listen
### Step 2: Access the Import Data Feature
1. Open your study and navigate to the **Analysis** tab
2. Click **Details**
3. Scroll to the bottom of the Details page
4. Locate **Import Data** and click **Configure Import**
### Step 3: Upload and Configure Your .csv
1. Upload your **.csv file**
2. **Select the identifier column** from your .csv
3. **Select the corresponding identifier** from your Listen study (Listen ID, URL parameter, panel ID, etc.)
4. The system will **preview how many rows successfully match**
5. Review the match count — if it's lower than expected, check your identifier for formatting inconsistencies
6. Click **Import** to complete the process
### Step 4: Use Your Imported Data
Once imported, your external data is available in three places:
**Bar Charts (Details Tab)**
Imported categorical fields automatically populate as bar charts at the bottom of the Details tab for quick visual exploration.
**Segments**
Imported fields can be used to create Segments, just like screener answers or URL parameters. Go to the Segments button on the Details tab to create groups based on your imported attributes.
**Responses Table**
Each imported field appears as a new column in the Responses tab, allowing you to sort, filter, and review participant-level data with your external attributes visible.
### Step 5: Create Segments from Imported Data
1. Go to the **Segments** button on the Details tab
2. Click **Add segment**
3. Select your imported field as the segmentation criterion
4. Define your groups (e.g., "Enterprise" vs. "SMB" based on a CRM plan type field)
5. For Advanced Segments, combine imported fields with other criteria using AND/OR logic
6. Click **Create Segment Group** and refresh to see the segments reflected in your analysis
#### Frequently Asked Questions
**What happens if some rows don't match?**
Only matched rows are imported. Unmatched rows are ignored and won't appear in charts, Segments, or the Responses table.
**Can I re-upload data?**
Yes. You can re-import updated files — this replaces any previously uploaded .csv data.
**Does imported data affect recruitment?**
No. Imported data is used for analysis only. Recruitment is controlled by screeners and quotas.
**Can imported data be used in Advanced Segments?**
Yes. Imported fields can be combined with other attributes using AND/OR logic in the Advanced Segment builder.
***
**Anything missing?** Let us know at [support@listenlabs.ai](mailto:support@listenlabs.ai) and we'll help you out!
# Integrating with Decipher (Forsta)
Source: https://docs.listenlabs.ai/integrating-with-forsta
Producing great research involves gathering a mix of both quantitative and qualitative data. Listen offers both of these capabilities, but if you can't accomplish what you need to in Listen alone then you can combine Listen with Decipher.
Decipher is a research tool geared toward collecting quantitative data via surveys. By integrating Decipher with Listen, a single set of participants can respond to both a Decipher survey and a Listen interview. Luckily, integrating these two platforms is easy for researchers and participants.
## How It Works
The flow of the study will look like this:
1. Participants start by filling out part of a Decipher survey.
2. They are then seamlessly redirected to Listen for an AI interview.
3. Finally, they are brought back to Decipher, continuing where they left off.
4. Researchers are then able to analyze both Decipher & Listen data across all responses.
Given this structure, we need to tell Decipher how to redirect to Listen, and then we need to tell Listen how to redirect back to Decipher, all while preserving participant IDs across platforms.
[*URL parameters play an important role in this process. For more information on URL Parameters, please check out our article on the subject.*](/setup-to-launch/question-routing)
Let's walk through how you can set this up for your own study:
## Redirecting from Decipher to Listen
At some point during the Decipher survey, participants need to be redirected to Listen to start their AI interview.
### Step 1: Copy Participant Link
Navigate to the "Share" page within your Listen Study. Once there, you can find and copy your Participant Link.
### Step 2: Create Redirect in Decipher
Navigate to the Survey Editor in Decipher and follow these instructions from the Decipher documentation to add a Redirect Logic Node.
When creating your Redirect element, make sure you paste your Participant Link from Listen into the URL field.
Add your Participant ID Query Parameter (usually "rid") & Participant ID Value (usually "\$uuid") to their respective fields. If needed, add any other URL parameters to the Extra Parameters field.
This ensures that when the user returns to Decipher, they can resume the survey at the correct spot. It also means that the Listen & Decipher responses can be matched by participant ID when you're analyzing your response data.
### Step 3 (Optional): Add URL Parameters to Listen
Adding URL parameters manually means they will show up as their own column on the "Responses" page, which makes it easier to see which participants made it to the Listen interview.
Even if you don't add them, all URL parameters will be captured by Listen and included in the response data, just not as their own columns.
Navigate to the "Create" page in Listen, and, switch to the "Config" tab.
Add a URL parameter by clicking "Add another URL parameter" and entering the name of the parameter. Add each of the parameters you created in Decipher.
## Redirecting back to Decipher
Once participants complete their Listen interview, they can be redirected back to finish their Decipher survey.
### Step 1: Activate Redirect on Complete
Navigate to the "Questions" tab on the "Create" page within your Listen study. Below your Questions, in the "Interview End" section, activate the "Redirect on Complete" switch.
### Step 2: Add Decipher Link
In the Redirect URL field, paste your Decipher survey link.
### Step 3: Keep URL Parameters
If the "Keep existing URL parameters" switch is activated, you don't need to include any URL parameters in the Redirect URL you just pasted.
Listen will automatically ingest the URL parameters from the original redirect from Decipher (including "rid" and any extra parameters you added) and send those back as part of the Redirect URL.
*The Redirect URL will still work if you include URL parameters with it. Any new parameters you add to the URL will still be included, and any duplicates will be removed.*
## Validate
### Try It Live
You're all set up! In order to validate that the integration is working, you can go through the Decipher survey yourself, including being redirected to Listen and back.
You can then hide your test data via the "Responses" page in Listen to prevent mixing up test data with live data. The Analysis page will update once you get real responses.
You should also remove your test data from the Decipher survey responses.
## Next Steps
Now you're ready to integrate with Decipher! For more detailed assistance, please reach out to our support team via [support@listenlabs.ai](mailto:support@listenlabs.ai).
# Integrating with Qualtrics
Source: https://docs.listenlabs.ai/integrating-with-qualtrics
Producing great research involves gathering a mix of both quantitative and qualitative data. Listen offers both of these capabilities, but if you can't accomplish what you need to in Listen alone then you can combine Listen with Qualtrics.
Qualtrics is a research tool geared toward collecting quantitative data via surveys. By integrating Qualtrics with Listen, a single set of participants can respond to both a Qualtrics survey and a Listen interview. Luckily, integrating these two platforms is easy for researchers and participants.
## How It Works
The flow of the study will look like this:
1. Participants start by filling out a Qualtrics survey.
2. They are then seamlessly redirected to Listen for an AI interview.
3. Researchers are then able to analyze both Qualtrics & Listen data across all responses.
Given this structure, we need to tell Qualtrics how to redirect to Listen while preserving participant IDs across platforms.
[*URL parameters play an important role in this process. For more information on URL Parameters, please check out our article on the subject.*](/setup-to-launch/question-routing)
Let's walk through how you can set this up for your own study:
## Redirecting from Qualtrics to Listen
At the end of the Qualtrics survey, participants need to be redirected to Listen to start their AI interview.
### Step 1: Copy Participant Link
Navigate to the "Share" page within your Listen Study. Once there, you can find and copy your Participant Link.
### Step 2: Create Redirect in Qualtrics
Navigate to the survey builder in Qualtrics. Scroll to the bottom and click "End of Survey". On the left under "Messaging", click the dropdown and select "Redirect to URL".
Paste your Listen Participant Link, with `?ResponseID=${e://Field/ResponseID}` appended at the end. So your final URL should look like:
```
https://listenlabs.ai/s/xxx123?ResponseID=${e://Field/ResponseID}
```
This ensures that the Listen & Qualtrics responses can be matched by Response ID when you're analyzing your response data.
### Step 3 (Optional): Add URL Parameters to Listen
Adding URL parameters manually means they will show up as their own column on the "Responses" page, which makes it easier to see which participants made it to the Listen interview.
Even if you don't add them, all URL parameters will be captured by Listen and included in the response data, just not as their own columns.
Navigate to the "Create" page in Listen, and, switch to the "Config" tab.
Add a URL parameter by clicking "Add another URL parameter" and entering the name of the parameter. Add each of the parameters being sent from Qualtrics, such as ResponseID.
## Validate
### Try It Live
You're all set up! In order to validate that the integration is working, you can go through the Qualtrics survey yourself, including being redirected to Listen at the end.
You can then hide your test data via the "Responses" page in Listen to prevent mixing up test data with live data. The Analysis page will update once you get real responses.
You should also remove your test data from the Qualtrics survey responses.
# Integrating with Rally
Source: https://docs.listenlabs.ai/integrating-with-rally
We've partnered with [Rally](https://www.rallyuxr.com) to make it easy to send participants from Rally directly into a Listen Labs study, while keeping their IDs intact and completion status synced between both platforms.
***
## How it works:
1. Participants join your Rally study.
2. They are redirected to your Listen Labs study.
3. They are automatically redirected back to Rally upon completion (no need to set up redirects on the Listen side).
4. Their participant status in Rally automatically updates to In Progress, then to Complete.
***
## How to set it up:
### 1. Build your Listen Labs study.
Finalize the setup of your study within the Listen platform.
### 2. Copy Participant Link
In Listen, go to the **Share** or **Recruit** page and copy your Participant Link.
### 3. In Rally, create a new Unmoderated Test.
When prompted to select the app used for the test, choose **Listen Labs**. Enter the Listen Labs link you copied as the test URL.
### 4. Complete the setup in Rally, and begin fielding!
***
## Connecting Data Between Rally and Listen Labs
Rally will automatically pass Participant ID and Study ID to Listen Labs via URL Parameters. You can use this to help track completion, connect records, or import additional data to your Listen Labs study.
### Viewing One Participant's URL Parameters
You can view these under the URL Parameters section of each participant's interview transcript.
### Displaying URL Parameters in your Listen Labs Responses Table
Listen will not display these parameters in your Responses table by default, but you can add them:
1. Go back to your Study Editor (Click "Edit" in the upper right)
2. Go to Study Settings (Click the wrench icon on the left side)
3. Scroll down to URL Parameters and press + Add another URL parameter
4. Type in the matching URL parameter name: "pid" or "studyID"
5. View the new columns for each URL parameter in your Responses table, or export the table.
Have any questions? Reach out to [support@listenlabs.ai](mailto:support@listenlabs.ai)
# Responses Tab & Transcripts
Source: https://docs.listenlabs.ai/interview-data/interview-grid-and-transcripts
Monitor incoming interviews in real time, review full transcripts, and manage your participant data
Once your study is live, the Responses tab becomes your command center for tracking incoming data. As participants complete interviews, you can view their individual responses, full conversation transcripts, and video recordings — all in one place.
![Screenshot2026 02 25at11 30 58PM]()
### Key Concepts Explained
**Responses Tab**: Your real-time dashboard for monitoring all incoming interview data. Shows participant-level data including full transcripts, screener responses, and completion status as interviews arrive.
**Transcript**: The complete text of each interview conversation — AI Interviewer questions and participant answers — automatically generated from audio or video recordings. Transcripts are used by all AI analysis features.
**Video Recording**: A recording of the participant's interview session. Click into any response to watch participants respond and understand non-verbal cues alongside what they said.
**Hide Response**: A way to remove a specific response from analysis without permanently deleting it. Hidden responses can still be viewed by toggling the display at the top of the response table.
### Pro Tips
* **Review transcripts early**: Read a handful of raw transcripts before running AI analysis — this builds intuition for what the data contains and helps you interpret AI findings more critically.
* **Use column customization**: Right-click on column headers to select which data columns to display. Rearrange columns using the 3-stacked-bar icon in each column to create your ideal analysis view.
* **Filter to find patterns**: Filter responses by themes, multiple-choice options, or specific words mentioned to quickly identify patterns across interviews.
* **Hide low-quality responses**: If a response appears fraudulent or incoherent, select its ID in the first column and click "Hide" at the bottom left. This keeps your data clean without deleting anything permanently.
### Quick Reference
| Action | How To |
| --------------------------- | --------------------------------------------------- |
| View full transcript | Click any response row |
| Watch video recording | Click into response → video player |
| Export data | Click Export → choose CSV, Excel, or Google Sheets |
| Customize columns | Right-click column headers |
| Filter responses | Use filter options (themes, MC answers, keywords) |
| Hide a response | Select participant ID → click "Hide" at bottom left |
| View hidden/screen-out data | Click "Responses" at top left of response table |
***
## Complete Written Guide
### Step 1: Access the Responses Tab
1. Open your study from the Listen Labs dashboard
2. Click on the **Responses** tab
3. You'll see a row for each participant who accessed your study link, including completions, screen-outs, and in-progress interviews
### Step 2: Monitor Incoming Responses in Real Time
During active recruitment:
* **Watch responses arrive as they happen** — the dashboard updates in real time
* Review **respondent-level data** for each participant, including screener answers and completion timestamps
* Track your **completion rate** and watch for patterns in screener drop-off that might indicate recruitment issues
### Step 3: View Full Transcripts
1. Click into any response row
2. The **full transcript** opens, showing the complete conversation between the AI interviewer and the participant
3. The transcript includes the AI's questions, follow-up probes, and all participant responses
Click into any response to also access **video recordings** of participants responding — a powerful way to understand non-verbal cues alongside what was said.
### Step 4: Customize Your View
**Column Customization:**
1. Right-click on column headers to select which data columns to display
2. Use the **3-stacked-bar icon** in each column to rearrange columns into your preferred order
3. Create logical data views that enable side-by-side comparison of related questions
**Filter Responses:**
1. Use the filter options to narrow responses by:
* Themes identified in the data
* Multiple-choice question answers
* Specific words or keywords mentioned
2. Quickly surface responses relevant to key topics and identify patterns across interviews
### Step 5: Export Response Data
1. Click the **Export** button in the Responses tab
2. Choose your format:
* **CSV** for spreadsheet analysis
* **Excel** for formatted workbooks
* **Google Sheets** for collaborative review
3. Select which fields to include and download
### Step 6: Hide Responses
To remove a low-quality or fraudulent response from analysis:
1. Select the participant's **ID** in the first column of the table
2. Click **Hide** at the bottom left
3. The response is excluded from analysis views but is not permanently deleted
To view hidden responses or screen-out data:
1. Click **Responses** at the top left of the response table
2. Toggle between active, hidden, and screen-out response views
***
**Anything missing?** Let us know at [support@listenlabs.ai](mailto:support@listenlabs.ai) and we'll help you out!
# Analysis 101
Source: https://docs.listenlabs.ai/interview-data/talk-to-your-data
How to use Listen to get instant Insights
Listen's Analysis tools transforms raw interviews into structured findings automatically. Once your interviews are complete, head to the Analysis tab to explore your data across three purpose-built views: Report, Details, and Chat.
Each view is designed for a different stage of the analysis process, from high-level summaries to granular deep dives to open-ended exploration. This guide walks you through every part of the experience so you know exactly where to look for what you need.
## Report
The Report tab generates a narrative organized around your study objectives. Think of it as your goals-first view — it shows how your research answers the specific questions you came in with.
Each study objective gets its own section with relevant findings pulled directly from participant responses. Live charts are embedded alongside the narrative so you can see patterns at a glance, and every data point links back to the individual responses behind it. The full report is shareable and exportable, making it easy to hand off to stakeholders without additional formatting.
Use the Report tab for executive summaries, stakeholder updates, and answering the question: "Did we learn what we came to learn?"
## Details
The Details tab is your comprehensive, question-by-question analysis view. This is where you go for depth. For each question in your study, you get:
* **AI-generated summaries** that concisely synthesize what participants said across all responses.
* **Theme analysis** with auto-generated themes drawn from response data. Click any theme to read the underlying responses, and edit labels, merge, split, or recode themes to match your team's language.
* **Outlier detection** that surfaces surprising or minority perspectives — these often signal emerging trends worth investigating.
* **Video highlights** — compilation clips with closed captioning that show the most relevant responses.
* **Quantitative breakdowns** that give you a statistical view of qualitative responses organized by theme.
* **Segment comparisons** that let you compare responses across audience groups side by side (more on segments below).
From the Details tab you can also generate ready-to-present PowerPoint slides with visualized data and key findings. Download them directly for immediate sharing, or generate multiple targeted decks focused on different questions or segments and combine the best slides into a final presentation.
Use the Details tab for deep-dive analysis, understanding the "why" behind the data, and building presentation materials.
## Chat (Research Agent)
The Chat tab lets you ask questions about your data in plain English. The Research Agent answers with citations linked to specific participants and timestamps, so you can always verify the source.
This is especially powerful for exploratory analysis and for finding supporting evidence for findings you've already identified. Some example prompts to get started:
* "What do younger users think about the product design?"
* "What common pain points did participants mention?"
* "Which concept generated the most positive emotional responses?"
* "Show me quotes from participants who mentioned price as a concern."
* "How does usage intent compare for Segment Group A vs. Group B?"
* "Summarize what participants said about \[research objective]"
A quick tip: be specific. "What do younger users think about the product design?" will get you better results than "What do people think?"
Use the Chat tab for exploratory analysis, answering specific questions quickly, and finding supporting evidence for key findings.
## Working With Segments
Segments let you split participants into groups based on shared characteristics so you can compare how different audiences responded. You can define segments using screener question answers, multiple-choice answers from within your study, URL parameters passed into the study link, panel-provided respondent data, or imported CSV data appended to your study.
Once segments are set up, you can compare responses side by side across charts, AI summaries, and qualitative responses in the Details tab. You can also ask the Chat tab for segment-level comparisons directly.
For the best results, plan your segments before launching your study. Design your screener questions, quotas, and URL parameters with your intended comparisons in mind — it's much easier to set this up before data collection than after. If a segment has fewer than 10 responses, treat its insights as directional indicators rather than statistically significant findings.
You can create advanced segments that combine multiple conditions using AND/OR logic. For example, you could combine gender with streaming subscriptions to create segments like "Female Netflix Subscribers" and "Male Netflix Subscribers."
## Editing and Refining Your Analysis
Listen's automated analysis is a starting point, not a final answer. You have full control to refine the output:
* **Edit theme labels** to match your team's terminology and frameworks.
* **Merge overlapping themes** or **split themes** that are too broad to be useful.
* **Hide invalid responses** from the analysis without permanently deleting them.
* **Add annotations and notes** to capture your own observations alongside the AI-generated findings.
## Exporting Your Work
You can export your analysis in several formats depending on what you need:
* **Full report** as a shareable link or PDF
* **PowerPoint slides** generated from the Details tab or by Listen's Research Agent
* **Response data** as CSV, Excel, or Google Sheets
* **Video clips and highlight reels** (see the [Custom Clips](/interview-data/custom-clips) article for details)
Generate multiple targeted PowerPoints focused on different questions or segments, then combine the best slides into a final deck.
# Connect Your MCP Client
Source: https://docs.listenlabs.ai/mcp-docs/connect
Add the Listen Labs MCP server to Claude, ChatGPT, or Codex and authenticate with OAuth.
For every client below: after adding the connector, click **Connect**, sign in to Listen Labs when prompted, click **Approve**, and start chatting.
## ChatGPT
Listen Labs is officially available in the OpenAI App Store. Add it directly:
[Add Listen Labs in ChatGPT](https://chatgpt.com/apps/listen-labs/asdk_app_6a0765f330f08191a2e5d95f075948a9)
Or, in ChatGPT go to **Apps** → search **Listen Labs** → add the connector.
## Claude
Listen Labs is officially available in the Claude connector directory. Add it directly:
[Add Listen Labs in Claude](https://claude.ai/directory/connectors/listen-labs)
Or, in Claude go to **Customize** → **Connectors** → **Browse connectors** → search **Listen Labs** → **Connect**, then log in and approve access.
Prefer plain-English research workflows? Add the [Listen Labs research skill](https://github.com/MerlinAGI/listen-labs-research-skill) on top of the connector to create, launch, and analyze studies without touching the raw tools.
## Codex
[Setup video](https://www.loom.com/share/4cf84f2e963a42c58795c1dedd164b65)
Open your terminal.
```bash theme={null}
codex mcp add listenlabs --url https://listenlabs.ai/mcp
```
Log in, approve access, and use.
## Server URL
```
https://listenlabs.ai/mcp
```
You can also use `https://mcp.listenlabs.ai/mcp` (equivalent endpoint).
The server uses **stateless Streamable HTTP**: each request is independent. There are no long-lived MCP sessions to manage.
## First-time authentication
Your MCP client discovers OAuth metadata from the server automatically.
You are redirected to `https://listenlabs.ai/mcp/authorize` (or prompted to sign in first).
The consent screen shows which application is requesting access and what it can do.
After you approve, the client receives access and refresh tokens.
### Token lifetimes
| Token | Lifetime | Notes |
| ------------- | -------- | ------------------------------------- |
| Access token | 1 hour | Refreshed automatically by the client |
| Refresh token | 30 days | Re-authorize if it expires |
You can revoke access by removing the MCP server from your client. OAuth client registrations that go unused are cleaned up automatically after 90 days.
## Permissions
When you approve access, the MCP integration can:
* View studies and their details in organizations you belong to
* Read completed respondent transcripts and analysis from those studies
* Create and edit studies where you have edit access
* Launch studies and start recruitment where you have permission to do so
* Organize studies into folders, and create, rename, move, or delete folders
The integration acts **as you** and respects the same permissions as the web app. It only sees and changes studies your Listen Labs user already has access to. Creating and editing require edit access on the study or organization, launching requires permission to start recruitment, and read-only tools require at least view access.
# Listen Labs MCP
Source: https://docs.listenlabs.ai/mcp-docs/index
Connect AI assistants (Claude, ChatGPT, Codex, and other MCP clients) to your Listen Labs account.
Connect AI assistants — Claude, ChatGPT, Codex, and other MCP clients — to your Listen Labs account. Create, edit, and launch studies, ask questions about study results, browse respondent transcripts, and search across studies straight from your AI client.
## What you can do
| Capability | Description |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| Create studies | Describe a research goal and walk through a guided setup (goals, audience, interview mode, study guide) |
| Edit studies | Change titles, questions, screeners, recruitment, interview mode, concepts, incentives, languages, and more in natural language |
| Launch studies | Publish your latest edits and start recruitment when you're ready to go live |
| Browse studies | List studies you can access, filter by title, status, or folder, see response counts and whether analysis is ready |
| Organize studies | File a study into a folder when you create it, move it later, or return it to the dashboard |
| Manage folders | Create nested folders, rename them, re-nest them, and delete empty ones |
| Search research | Find studies and themes by keyword across titles, goals, classifications, and analysis themes |
| Read transcripts | Pull paginated respondent interview transcripts with deep links back to Listen Labs |
| Read analysis | Fetch AI-generated analysis reports (markdown) with sourced quotes |
## Requirements
* A Listen Labs account with access to at least one organization
* An MCP client that supports remote MCP servers with OAuth
## Quick Start
Add the Listen Labs MCP server to Claude, ChatGPT, or Codex and authenticate with OAuth.
## Permissions
When you approve access, the MCP integration can:
* View studies and their details in organizations you belong to
* Read completed respondent transcripts and analysis from those studies
* Create and edit studies where you have edit access
* Launch studies and start recruitment where you have permission to do so
* Organize studies into folders, and create, rename, move, or delete folders
The integration acts **as you** and respects the same permissions as the web app. It only sees and changes studies your Listen Labs user already has access to. Creating and editing require edit access on the study or organization, launching requires permission to start recruitment, and read-only tools require at least view access.
## Server URL
```
https://listenlabs.ai/mcp
```
You can also use `https://mcp.listenlabs.ai/mcp` (equivalent endpoint).
The server uses **stateless Streamable HTTP**: each request is independent. There are no long-lived MCP sessions to manage.
# Troubleshooting & Reference
Source: https://docs.listenlabs.ai/mcp-docs/troubleshooting
Fixes for common MCP connection issues, plus technical details and support contacts.
## Troubleshooting
* Confirm you are signed in to Listen Labs in the browser that opens for consent
* Remove and re-add the MCP server in your client to trigger a fresh OAuth flow
* Check that your client supports remote OAuth MCP (not only local stdio servers)
Your Listen Labs user does not have access to that study's organization. Verify access in the dashboard.
`get_study_analysis` requires a completed analysis run. Check `list_studies` for `has_analysis: true`. New or in-progress studies may not have analysis yet.
The server is stateless and only accepts `POST` on `/mcp`. Ensure your client uses Streamable HTTP, not SSE session polling on `GET /mcp`.
Another edit or save is in progress. Wait a moment and try again.
Your role may allow editing but not starting recruitment. Ask an admin for launch permissions.
Edits on live studies stay in draft until published. Ask your assistant to publish or launch the study.
That folder name is used in more than one place. The error lists the full path of each match, so repeat your request with the full path, such as `Research / Q3 2026`.
Filing a study requires a folder that already exists. The error lists the folders that do exist. Pick one of those, or ask your assistant to create the folder first.
Only empty folders can be deleted. Move the studies and subfolders out first, then delete.
Folder study counts describe the whole folder. They ignore keyword and status filters, so they will not match a filtered list of studies. This is expected.
## Technical details
| Item | Value |
| -------------- | ---------------------------------------------------------- |
| Protocol | [Model Context Protocol](https://modelcontextprotocol.io/) |
| Transport | Streamable HTTP (stateless) |
| Auth | OAuth 2.1 with dynamic client registration |
| Server name | `Listen Labs` |
| Server version | `1.0.0` |
## Support
For account access, billing, or feature requests, contact your Listen Labs team at [support@listenlabs.ai](mailto:support@listenlabs.ai) or visit [listenlabs.ai](https://listenlabs.ai).
# Endpoint
Source: https://docs.listenlabs.ai/method-1
These endpoints all authenticate with the `x-api-key` header (see [Get API Access](/request-api)). The create, launch, and wallet endpoints below build and launch studies; the response and study endpoints further down retrieve data from studies that are already live. For the full study-guide schema (every block type, question type, conditional, and validation rule) see the [Study Creation API reference](/api-v2/overview).
# Create Study
Validates a study guide and creates a **draft** study in the API key's organization. Nothing is visible to participants until you launch it.
`POST https://listenlabs.ai/api/public/v1/studies/create`
### Request Body
`title string required`
Internal title of the study.
`externalTitle string`
Title shown to participants.
`background string`
Context about your company or product that the interviewer can draw on.
`studyGoal string`
What you are trying to learn. Guides the interviewer's follow-ups.
`config object`
Interview settings. `interviewMode` (`text`, `audio`, `audio_text`, `audio_screen`, `video`, `video_screen`), `questionLanguage` (e.g. `en`, `de`), optional `availableLanguages` for auto-translation, and optional `targetPlatforms`.
`welcomeMessage object`
Optional `title` and `message` shown before the interview starts.
`closingMessage string`
Message shown when the interview ends.
`studyGuide Block[] required`
The ordered list of blocks that make up the interview. Each block has a `type` (`flat`, `concept`, or `screening`), a `title`, and an `items` array of questions. See the [Study Guide Reference](/api-v2/study-guide) for the complete schema, all question types, conditionals, carry-forward, and cross-field validation rules.
### Response
`id uuid`
Permanent unique identifier for the study. Use it to launch.
`linkId string`
The link ID of the study (editable later in study settings). Use it with the response endpoints.
`status string`
Always `draft` for a freshly created study.
### Example Request
```bash theme={null}
curl -X POST 'https://listenlabs.ai/api/public/v1/studies/create' \
-H 'x-api-key: ' \
-H 'Content-Type: application/json' \
-d '{
"title": "Coffee habits — API demo",
"externalTitle": "A short interview about your coffee routine",
"background": "We are a specialty coffee brand exploring how people choose what to buy.",
"studyGoal": "Understand what drives brand switching among regular coffee drinkers.",
"config": {
"interviewMode": "audio_text",
"questionLanguage": "en"
},
"welcomeMessage": {
"title": "Thanks for joining!",
"message": "This interview takes about 10 minutes. There are no wrong answers."
},
"closingMessage": "That is all — thank you for your time!",
"studyGuide": [
{
"type": "screening",
"title": "Screener",
"items": [
{
"type": "multiple_choice",
"text": "How often do you drink coffee?",
"options": [
{ "text": "Every day", "status": "approve" },
{ "text": "A few times a week", "status": "approve" },
{ "text": "Rarely or never", "status": "reject" }
]
}
]
},
{
"type": "flat",
"title": "Interview",
"items": [
{
"externalId": "purchase-channels",
"type": "multiple_choice",
"text": "Where do you usually buy coffee?",
"multiSelect": true,
"options": [
{ "externalId": "opt-cafe", "text": "Cafés" },
{ "externalId": "opt-grocery", "text": "Grocery stores" },
{ "externalId": "opt-online", "text": "Online" },
{ "text": "Somewhere else", "exclusiveOption": true }
]
},
{
"type": "open_ended",
"text": "What do you like about buying coffee online?",
"followUp": "medium",
"conditional": {
"operator": "and",
"criteria": [
{
"type": "selectedTemplateOptions",
"questionId": "purchase-channels",
"matchingCriteria": "mustSelect",
"choices": ["opt-online"]
}
]
}
},
{
"type": "open_ended",
"text": "Tell me about the last time you tried a new coffee brand.",
"followUp": "heavy"
}
]
}
]
}'
```
### Example Response
```json theme={null}
{
"id": "9b2f1c3e-0000-0000-0000-000000000000",
"linkId": "coffee-habits-api-demo",
"status": "draft"
}
```
### Errors
Every error response returns an `error` message and a stable `code` you should branch on. `400` schema failures (`code: invalid_request_body`) also include an `issues` array pointing at the offending fields; broken study-guide rules return `code: invalid_study_guide`.
```json theme={null}
{
"error": "Invalid request body",
"code": "invalid_request_body",
"issues": [
{ "path": ["title"], "message": "Required" }
]
}
```
***
# Launch Study
Publishes a draft and returns its self-recruit link. Requires the API key's user to have permission to start recruitment on the study. Project responses bill to the launch wallet.
`POST https://listenlabs.ai/api/public/v1/studies/{studyId}/launch`
### Path Parameters
`studyId uuid`
The study's permanent `id` returned from Create Study or List Studies. The `linkId` is not accepted here.
### Request Body
The body is optional.
`walletId uuid`
Wallet to bill this study from; must be granted to the API key's organization (see List Wallets). It can only be omitted when the organization has exactly one wallet, which is then auto-selected. If you have access to more than one wallet, omitting it returns a `400` (`code: wallet_required`).
### Response
`id uuid`
The study's permanent identifier.
`linkId string`
The link ID of the study.
`selfRecruitLink string`
The public link to share with participants.
`status string`
Always `live` after a successful launch.
`wallet object`
The wallet this launch is billed to. Omitted when no wallet is bound (organization without wallet billing).
### Example Request
```bash theme={null}
curl -X POST 'https://listenlabs.ai/api/public/v1/studies/9b2f1c3e-0000-0000-0000-000000000000/launch' \
-H 'x-api-key: ' \
-H 'Content-Type: application/json' \
-d '{ "walletId": "5e8a7d40-0000-0000-0000-000000000000" }'
```
### Example Response
```json theme={null}
{
"id": "9b2f1c3e-0000-0000-0000-000000000000",
"linkId": "coffee-habits-api-demo",
"selfRecruitLink": "https://listenlabs.ai/s/coffee-habits-api-demo",
"status": "live",
"wallet": {
"walletId": "5e8a7d40-0000-0000-0000-000000000000",
"name": "Research team",
"recruitmentCreditBalance": { "balance": 480, "usage": 20 },
"projectCreditBalance": { "balance": 950, "usage": 50 }
}
}
```
### Errors
| Status | Code | Meaning |
| ------ | -------------------------- | -------------------------------------------------------------------------------------- |
| `400` | `wallet_required` | The organization has multiple wallets and `walletId` was omitted. |
| `400` | `insufficient_credits` | The wallet can't fund the launch (insufficient balance or grant limit). |
| `403` | `launch_permission_denied` | The key's user lacks permission to launch this study. |
| `403` | `wallet_access_denied` | No access to the specified wallet. |
| `404` | `study_not_found` | Study not found in the key's organization. |
| `409` | `study_busy` / `conflict` | The study is mid-update or the publish raced a concurrent edit — retry after a moment. |
***
# List Wallets
Lists the wallets granted to the API key's organization, each with recruitment and project credit balances. Use a wallet's `walletId` when launching a study.
`GET https://listenlabs.ai/api/public/v1/wallets`
### Response
`wallets Wallet[]`
Each wallet is an object with the following fields:
* `walletId uuid` — Identifier to pass when launching a study.
* `name string` — Human-readable wallet name.
* `recruitmentCreditBalance object` — Credits for recruiting participants. Has `balance` and `usage` (includes active holds).
* `projectCreditBalance object` — Credits for project responses. Same `balance` / `usage` shape.
### Example Request
```bash theme={null}
curl 'https://listenlabs.ai/api/public/v1/wallets' \
-H 'x-api-key: '
```
### Example Response
```json theme={null}
{
"wallets": [
{
"walletId": "5e8a7d40-0000-0000-0000-000000000000",
"name": "Research team",
"recruitmentCreditBalance": { "balance": 480, "usage": 20 },
"projectCreditBalance": { "balance": 950, "usage": 50 }
}
]
}
```
***
# 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 whose 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.
* `Summary string` — A summary of the entire conversation. Available for all studies.
* `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 Answer[]`
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. 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.
* `id string` — An id that is 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. Can be `null` if the transcript has not been generated yet.
`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.
`summary string`
A natural-language summary of the response. May be omitted from the payload when a summary has not yet been generated for the response.
### Example Request
```bash theme={null}
curl 'https://listenlabs.ai/api/public/responses/study123?page=0&per_page=100&updated_since=2023-08-18T00:00:00Z' \
-H 'x-api-key: '
```
### Example Response
```json theme={null}
[
{
"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": {
"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": "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": {
"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": "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 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. Matches the `id` field from the Get Study Questions endpoint, enabling you to join transcript rows with their question definitions.
* `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. Null for non-question rows (e.g. intro messages).
* `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, if available. This URL is valid for 1 hour. Null if no audio recording exists.
* `video object | null` — 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.
* `question_uuid string deprecated` — Deprecated. Use `discussion_guide_question_id` instead.
### Example Request
```bash theme={null}
curl 'https://listenlabs.ai/api/public/responses/study-1/12345678-0000-0000-0000-000000000000' \
-H 'x-api-key: '
```
### Example Response — Audio and Text
```json theme={null}
{
"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",
"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
```json theme={null}
{
"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
```json theme={null}
{
"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 all questions for a specific study.
`GET https://listenlabs.ai/api/public/studies/{study_id}/questions`
### Path Parameters
`study_id string`
The `link_id` of the study you want to retrieve questions for. You can find this in the study URL or via the List Studies endpoint. Only the `link_id` is accepted — not the study's `id` (the versioned endpoint accepts both).
### Response
Returns an object containing a list of questions from the study's latest revision. Each question includes its type and relevant metadata.
`questions array`
An array of question objects. Each question has a `type` field that determines its shape. All question types share these base fields:
* `id string` — Unique identifier for the question. Matches the `discussion_guide_question_id` field in the response endpoints, enabling you to join questions with their corresponding transcript rows and answers.
* `text string` — The question text shown to participants.
* `is_screener boolean` — Whether this question is part of the screening section.
* `type string` — The question type. One of: `open_ended`, `multiple_choice`, `ranking`, `statement`.
* `question_number number` — The human-readable question number for display purposes.
* `concepts array` — An array of concept objects 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` — An array of media attachments, each with a `type` (`image` or `video`), a `name`, and a `url`.
* `embed_url string | null` — An optional embed URL for the concept (e.g. a Figma or prototype link).
Multiple choice questions (including scale questions) additionally include:
* `is_multi_select boolean` — Whether the participant can select multiple options.
* `options string[]` — The list of answer options.
Ranking questions additionally include:
* `options string[]` — The list of items to rank.
### Example Request
```bash theme={null}
curl 'https://listenlabs.ai/api/public/studies/my-study/questions' \
-H 'x-api-key: '
```
### Example Response
```json theme={null}
{
"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+"],
"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"],
"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"],
"concepts": []
}
]
}
```
***
# 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 — it never changes. Accepted by the versioned launch, questions, and response endpoints.
`link_id string`
The link ID of the study — the path parameter for the response and questions endpoints. 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
```bash theme={null}
curl 'https://listenlabs.ai/api/public/list_surveys' \
-H 'x-api-key: '
```
### Example Response
```json theme={null}
[
{
"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 API Access
Source: https://docs.listenlabs.ai/request-api
# Authentication
**API key**
1. Go to your account page on Listen and open the **Developer** section. API keys can be created by Admins and Supervisors.
2. Create an API key.
3. Use it in your request in the `x-api-key` header.
```shellscript theme={null}
'x-api-key': 'abc123....'
```
Each API key is scoped to a single organization. It works with the data endpoints as well as the [Study Creation API](/api-v2/overview) for creating and launching studies.
# Seat Types & Permissions
Source: https://docs.listenlabs.ai/settings-and-management/account
Your Listen workspace is the organizational hub for your team's research. This article covers how to invite team members, understand seat types and permissions, and configure workspace-level settings that apply across all studies.
![Screenshot 2026 02 25 At 11 08 19 PM]()
## Seat Types & Permissions
### Organization Roles
* **Admin:** Full control over the organization — all studies, billing, workspace settings, and user management.
* **Researcher:** Can create and launch studies. The standard role for anyone actively running research.
* **Collaborator:** Can create and edit studies but cannot launch them. Great for team members who need review before going live.
### Team Roles
* **Manager:** Can admit new members to the team for a specific study.
* **Researcher (team):** Can edit and view all studies shared with that team.
### Automatic Permissions
* Organization Admins automatically get full access to all studies in the workspace.
* Study creators always have full access to their own studies, regardless of team role.
**New in February 2026:** The Collaborator role lets you scale research creation while keeping quality controls in place — Collaborators can build, but only Researchers and Admins can launch.
## Inviting Team Members
1. From your dashboard, click **Workspace** in the left navigation.
2. Select **Team Members**.
3. Click **Invite Member** and enter their email address.
4. Assign the appropriate role (Admin, Researcher, or Collaborator).
5. The invitee will receive an email with a link to join the workspace.
Invites expire after 7 days. If a team member hasn't accepted, resend from the Team Members page.
***
**Anything missing?** Let us know at [support@listenlabs.ai](mailto:support@listenlabs.ai) and we'll help you out!
# Account Page
Source: https://docs.listenlabs.ai/settings-and-management/account-page
The Account page is where you manage you view and personal profile and notification preferences.
* **Name** - Update your display name at any time
* **Email** – The email address associated with your Listen account
* **Notifications** Toggle notifications for key events such as;
* *Paused studies*
* Incoming responses
* *Quota milestones*
* Study status changes
* **Role** – Your assigned role in the Workspace. *Read more about assigned roles in the "Seat Types & Permissions" page*
# Workspace Guidelines
Source: https://docs.listenlabs.ai/settings-and-management/workspace-guidelines
As an Admin, you can set guidelines that automatically apply to every new study created in your workspace. This ensures research quality and brand consistency as your team scales.
### What Guidelines Can Include
* Required screening questions that appear in every new study
* Tone-of-voice instructions for the AI moderator
* Standard demographic questions applied across all discussion guides
* Company or brand context so the AI always has background information
### How to Set Guidelines
1. Go to the **Workspace** tab on your homepage.
2. Select **Study Guidelines**.
3. Write your guidelines in plain text — the AI interprets and applies them automatically.
4. Save. All new studies created after this point will incorporate these guidelines.
Guidelines apply to new studies only — they don't retroactively update existing ones. Update your guidelines before starting a new research cycle.
# Localizing Your Study: Auto-Translations
Source: https://docs.listenlabs.ai/setup-to-launch/auto-translations
Launch studies in multiple languages with automatic translation — no manual translation work required
Listen automatically translates your **entire interview guide** and all participant responses in seconds into **90+ supported languages**, so you can launch studies and analyze results across markets without waiting on manual translation work.
Whether you're testing concepts in Japan, running interviews in Brazil, or surveying users in France, multilingual research is as fast and seamless as English-only studies.
Looking to have interview questions read aloud in participants' language? See [Multilingual Voice Interviewer](/setup-to-launch/multi-lingual-voice-interviewer) for audio support across 40+ languages
## Configure Your Study Lanaguage
Your **Study Language** determines:
* The language you write your study in
* The language your analysis report will be generated in
You can change it under the "**Language**" section at the top of your Discussion Guide.
By default, this is set to **English**. You can toggle this off if your Study Language is set to a different language, and you would like the analysis to be run in that respective language.
![Screenshot 2026 03 20 At 12 14 12 PM]()
## Turning On Translations
To make your study available in multiple languages:
![Screenshot 2026 03 20 At 12 16 03 PM]()
1. In this same **"Language"** section, click the ["](https://listen-labs.slack.com/archives/C070U1WMZEY/p1773256279931529)**+ Add Translations"** and select from the drop down. Find the complete list of available languages [here](/setup-to-launch/languages-complete-list).
2. Toggle on **Read Questions Aloud** if you would like the interviewer to read the questions in the respective language.
3. You can customize the voice of your interviewer across multiple languages
![Screenshot 2026 03 20 At 1 34 14 PM]()
When Translations are enabled:
* Participants will automatically see your study in their **browser’s default language** (if available).
* If their browser language isn’t supported, they’ll see the **study language** instead.
## Reviewing and Editing Translations
You have two ways to review translated content:
* **Preview in Platform:** In the Discussion Guide view click the **language icon** in the upper-right corner to update the guide to be available in the respective languages.
![Screenshot 2026 03 20 At 1 39 17 PM]()
* **Export for Review:** In the same upper right hand corne you can export a **.csv** or **Word document** of your discussion guide in each language for translation review or external proofreading.
![Screenshot 2026 03 20 At 1 35 59 PM]()
## Analyzing Results Across Languages
When a participant completes your study in another language, their **responses and transcripts are automatically translated** back into your Study Language for analysis.
This process happens instantly — no need to wait for manual translation or export files.
That means:
* You’ll see all individual responses in your **Study Language** (e.g., English) by default.
* Your **Reports**, **Responses Table,** **Details**, **Chat responses, Charts**, and other key insights will show in your **Study Language**.
* The **original-language transcript** is also stored-- you can toggle between native language and Study Language in a participant's transcript window, or export them from the Responses tab.
![Screenshot2025 11 06at5 18 44PM]()
***
## FAQs
**Which languages does Listen Labs support?**
Listen Labs currently supports translations across \~100 languages. You’ll find the current list in your **Study Settings → Translations**
**Can I edit the translations or upload my own?**
Yes. Use the **Translation Guidance** field under **Settings → Translations** to specify preferred terms or paste an entire translated guide. The AI will apply your custom text instead of generating a translation.
![Screenshot2025 11 06at5 10 36PM]()
**Can I manually set the default language instead of relying on the browser?**
Yes. Append the language code to your participant link using the `lang=` URL parameter, then send the specific links to the appropriate regions.
For example, to default a study to Japanese, you would send this link:
```text theme={null}
![Ae68e991 Cd3e 46ec 8782 Cfdc436d70b6 1734720681265 Section]()
2. **Convert Section to Concept Test**
* Select the option to “Convert Section to Concept Test.” This will convert the Section to a Concept Test and create your first Concept.
![Ae68e991 Cd3e 46ec 8782 Cfdc436d70b6 1734720686839 Section Settings]()
### Creating and Editing Concepts
*Each Concept should be a creative or message that you want to test with your study participants.*
* **Add Concepts**
* Click “New Concept” to add a new concept.
* Alternatively: to auto-generate concepts based on media files, click or drag files into the file upload box to the left of the “New Concept” button.
![Ae68e991 Cd3e 46ec 8782 Cfdc436d70b6 1734720692009 New Concept]()
* **Edit Concepts**
* Edit the title and description of a Concept via the text boxes.
* Add media (images, videos, URL embeds) to a Concept by clicking the upload box marked “+”.
![Ae68e991 Cd3e 46ec 8782 Cfdc436d70b6 1734720701113 Concept Selection]()
* **Configure Concept Selection**
* You can choose how the Concepts will be shown to participants in the “Concept Selection” section.
* **Single Concept**: Participants will respond to one randomly selected Concept.
* **Custom Selection**: Participants will respond to multiple Concepts in a randomized order. The questions in this Section will be repeated for each Concept that is shown
![Ae68e991 Cd3e 46ec 8782 Cfdc436d70b6 1734720701113 Concept Selection 1]()
* **Exit Settings**
* Exit the Concept Test Settings by clicking the “X” in the top right corner.
### Using Concepts in Questions
*The Concepts you just created will apply to the Section you added them to, so the questions in this Section should be specific to the Concepts being tested.*
* **Dynamic Placeholders**
* Use `{{concept.title}}` and `{{concept.description}}` in your question text in order to dynamically reference whatever Concept is being shown to the participant.
![Ae68e991 Cd3e 46ec 8782 Cfdc436d70b6 1734720709210 Dynamic Placeholders]()
* **Display Concept Media**
* Click “Show Advanced Settings” and then activate the “Show Concept Media” switch in order to display the media from the current Concept for the participant to respond to.
![Ae68e991 Cd3e 46ec 8782 Cfdc436d70b6 1734720713758 Show Concept Media]()
* **Preview Concepts**
* Use the dropdown menu over the preview window to select a Concept to preview. This lets you see exactly what participants will experience when responding to that concept.
![Ae68e991 Cd3e 46ec 8782 Cfdc436d70b6 1734720719765 Concept Preview 1]()
***
**Anything missing?** Let us know at [support@listenlabs.ai](mailto:support@listenlabs.ai) and we'll help you out!
# Conditional Logic
Source: https://docs.listenlabs.ai/setup-to-launch/conditional-logic
Show or skip questions based on participant answers to create dynamic, relevant interview experiences
Conditional logic lets you show or skip questions based on how a participant answered an earlier question. This keeps interviews relevant, reduces fatigue, and enables more sophisticated research designs.
***
## How It Works
You set conditions on any question to make it display only when specific criteria are met — based on the answers to earlier multiple-choice or closed-ended questions.
**Example:** Show Question 5 only if the participant selected "Yes" in Question 3.
***
## Setting Up Conditional Logic
1. In the **Editor**, click into the question you want to conditionally show
2. Click **Show advanced settings**
3. Select the earlier multiple-choice question whose answer should trigger the condition
4. Choose the specific answer option(s) that should cause this question to appear
5. Add additional conditions if needed
![Screenshot2026 02 25at11 25 42PM]()
Conditions are evaluated in real time as the participant progresses. If a prior answer doesn't meet the condition, the question is silently skipped — participants never see an empty or broken screen.
***
## Multiple Conditions
You can add multiple conditions to a single question (AND logic — all conditions must be met).
**Example:** Show this question only if the participant is in the US AND selected "Premium" in Q2.
***
## URL Parameters & Recruits
You can also segment sample based on URL Parameters or the recruits in the recruit tab.
**Example:** Show this question only if parameter is "user".
***
## Common Use Cases
* **Concept-specific follow-ups:** Only show questions about Concept A to participants who were assigned Concept A.
* **Experience-based routing:** Ask different questions to customers vs. non-customers.
* **Emotional branching:** Show a "what went wrong?" question only to participants who gave a low rating.
* **Screener reinforcement:** Skip irrelevant discussion guide questions based on screener answers.
Test all conditional paths thoroughly using **"Run from Start"** or **"Open Preview"** before launching. Trace each path to confirm the right questions appear and none are shown incorrectly.
***
Questions about screensharing setup? Email [**support@listenlabs.ai**](mailto:support@listenlabs.ai)
# Screensharing (Mobile & Desktop)
Source: https://docs.listenlabs.ai/setup-to-launch/desktop-and-mobile-screensharing
Capture real screen activity alongside participant interviews for usability testing, app walkthroughs, and behavioral research
Listen's screen sharing capability lets participants share their screen during an interview — giving you real behavioral data alongside their verbal responses. This is ideal for usability testing, app walkthroughs, website testing, and any study where you need to see what participants are actually doing, not just hear what they say.
***
## What Is Screensharing in Listen?
When screensharing is enabled, participants are asked for permission to share their screen (or turn on video) at the start of each session. This creates a synchronized recording of their screen activity alongside the audio/video interview — so you can watch exactly where they click, hesitate, scroll, or get confused.
**Important:** Participants are always asked for permission each time they join a screensharing study. This ensures explicit, per-session consent and is especially important given Listen's new mobile app capabilities.
***
## Desktop Screen Sharing
Desktop screensharing works through the participant's browser. When they open the study link on a desktop device, they'll see a browser-native screen-sharing prompt.
### Setting Up Desktop Screensharing
1. Open your study in the **Editor**.
2. Click the **settings icon** (wrench) in the left sidebar to open **Project Settings**.
3. Under **Responses Format**, select **Screen & Video Recording**.
4. Save and proceed to launch.
![Screenshot2026 02 25at11 19 16PM]()
Participants can share their full screen, a specific application window, or a single browser tab.
***
## Mobile Screen Recording (iOS)
Mobile Screen Recording is Listen's most requested feature — and it's now live. Participants join via the Listen iOS app by opening their study link on their phone or scanning a QR code.
### What You Can Capture on Mobile
* Full native iOS app interactions, including app-switching and multitasking
* Real user journeys across multiple apps — not just yours
* Exact moments of friction and drop-off in the mobile experience
* Screen activity synchronized with the participant's verbal narration
![Screenshot2026 02 25at11 20 21PM]()
### How Participants Join Mobile Sessions
1. The participant receives their study link.
2. They open the link on their iPhone — this prompts them to download the **Listen iOS app** if not already installed.
3. They open the study inside the app, which handles screen recording permissions.
4. The interview runs inside the app, with screen recording capturing all activity.
***
## Reviewing Screensharing Data
Screen recordings appear alongside the standard video/audio in each participant's response. In the **Analysis** tab:
* Click into any response to watch the synchronized screen recording + interview.
* You can also toggle between the screenshare view and participant video.
* Screensharing clips can be included in highlight reels — contact support to enable.
* Look for hesitation, backtracking, and confusion in the recording — these often surface issues participants wouldn't volunteer verbally.
![Screenshot2026 02 25at11 23 04PM]()
***
Questions about screensharing setup? Email [**support@listenlabs.ai**](mailto:support@listenlabs.ai)
# Customizing Your Look & Feel
Source: https://docs.listenlabs.ai/setup-to-launch/detailed-topic-guide-settings
You can easily adjust how your study looks and feels to make it more engaging or on-brand for your audience. From formatting your text to adding logos and custom colors, here’s how to make your study your own.
### Formatting Text with Markdown
Markdown lets you add simple formatting—like bold, italics, and links.
This is especially helpful for emphasizing instructions, highlighting keywords, or linking to external resources (like product pages or privacy policies).
![Screenshot2025 10 30at1 12 43PM]()
**To use Markdown in Listen Labs:**
1. Go to your **Study Settings** by clicking the wrench icon on the left of your Create tab.
2. Toggle on “\*\*Enable markdown formatting in questions”, \*\*found at the bottom of your Study Settings
3. Then use the below structure to add formatting directly in your question text fields:
> * **Bold text** → `**bold text**`
> * *Italic text* → `*italic text*`
> * [Hyperlinks](https://listenlabs.ai/) → `[clickable text here]()`
> * ~~Strikethrough text~~ → `~strikethrough text~`
> * `Code blocks` → `code block`
![Screenshot2025 10 30at1 28 02PM]()
* **Upload a logo** – Add your brand or product logo to appear at the top of your study.
![Screenshot2025 10 30at1 31 38PM]()
* **Change colors** – Adjust the button, text, and background colors to match your brand palette.
![Screenshot2025 10 30at1 15 13PM]()
* \*\*Customize your link \*\*– You can change your Listen Labs study link path. Note: the old link will redirect to the new one.
![Screenshot2025 10 30at1 33 39PM 1]()
***
### 💡 When to Brand vs. Not Brand
* **Brand your study** if you’re recruiting from your own customer base or want participants to clearly recognize your organization.
* **Keep it neutral** (default Listen Labs styling) if you’re using a third-party panel or testing brand perceptions where your identity might bias responses.
***
**Anything missing?** Let us know at [support@listenlabs.ai](mailto:support@listenlabs.ai) and we'll help you out!
# Email Campaign
Source: https://docs.listenlabs.ai/setup-to-launch/email-campaign
## **Overview**
The Email Campaign feature lets you recruit participants for your Listen studies by sending email invitations directly from the platform.
> Note: Email campaigns are disabled by default. To enable this for your team, contact [support@listenlabs.ai](mailto:support@listenlabs.ai).
## **How It Works**
There are three ways to recruit participants via email for a Listen study. You can choose the approach that best fits your organization’s setup:
| **Option** | **How It Works** | **Best For** |
| :--------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------- |
| **Option A: Send from Listen (Default)** | Upload contacts directly to Listen. Emails are sent from Listen’s email domain on your behalf. No configuration needed — just upload and send. | Quick one-off campaigns or teams without an email tool. Note: deliverability may be lower since emails come from Listen’s shared domain. |
| **Option B: Use Your Own Email Platform** | Copy the study link from Listen and paste it into your email tool (Mailchimp, HubSpot, Salesforce, etc.). You manage the send entirely from your platform. | Teams with an existing email marketing stack. High sender reputation. |
| **Option C: Send from Your Domain via Listen** | Configure your DNS records so Listen’s email sender (Postmark) can send on behalf of your domain. Emails appear to come fro you, with full authentication. | Best deliverability. Emails appear from your brand. Recommended for large or recurring campaigns. |
![Screenshot 2026 03 20 At 1 44 53 PM]()
## **Sending a Campaign from Listen**
This section covers Options A and C, where you send emails directly through the Listen platform.
### **a. Prepare Your Contact List**
Create a CSV file with your contacts. At minimum, include an email address column. You can also include first name, last name, and any custom fields you’d like to use for personalization.
| **email** | **first\_name** | **last\_name** | **company** |
| :-------------------------------------- | :-------------- | :------------- | :---------- |
| [jane@acme.com](mailto:jane@acme.com) | Jane | Smith | Acme Corp |
| [alex@globex.io](mailto:alex@globex.io) | Alex | Johnson | Globex Inc |
### **b. Upload Contacts**
1. **Go to the Recruit tab** in your project.
2. **Click “Add Email Campaign**.”
3. **Select your CSV file.** Listen will parse the file and show you a preview of the contacts it found.
4. **Press “Compose Mail”.** Your contacts will appear in the campaign dashboard. Click continue.
5. **Edit email.** You can edit what the email will look like. The left hand side is the edit section, the right hand side is the working draft of what a recipient would see.
6. **Send!** You can send a test email to yourself, or feel free to fire off the emails!
## **Costs & Credits**
Understanding how credits and incentives work is important for planning your campaign budget.
### **a. Credit Usage**
Each completed study response costs 1 credit from your account balance. Credits are only consumed when a participant completes the study — sending emails and receiving clicks do not use credits.
### **b. Participant Incentives**
Participants receive an incentive for completing your study. The incentive amount is set when you configure your study, and the cost of incentives is your responsibility as the customer. Incentives are separate from credit costs.
| **Cost Component** | **Who Pays** |
| :------------------------------------------ | :------------------------------------------ |
| Platform credits (1 per completed response) | Deducted from your account credit balance |
| Participant incentives (per completion) | Customer responsibility — billed separately |
| Email sends | No additional cost |
## **Custom Domain Setup (Option C)**
For the best email deliverability, we recommend configuring Listen’s email sender (Postmark) to send from your own domain. This means recipients see your company’s email address in the “From” field, and email providers trust the message because it’s properly authenticated.
### **a. Setup Steps**
1. **Request DNS records from your CSM.** We’ll provide a set of DNS records specific to your domain.
2. **Add the records to your DNS provider.** Your IT team or domain admin adds the records to your domain’s DNS configuration. The exact steps depend on your DNS provider.
3. Ready to send emails per the steps provided in the Section above “**Sending a Campaign from Listen”.**
# Fraud Prevention & Quality Guard
Source: https://docs.listenlabs.ai/setup-to-launch/fraud-prevention-and-quality-guard
How Listen detects and removes fraudulent or low-effort responses to protect your research data
Research quality depends on the people you're talking to. If a participant is rushing through questions, copy-pasting answers, or gaming the system to collect an incentive, the data they produce can skew your analysis and undermine your findings.
Listen has built a multi-layer quality system — called **Quality Guard** — that detects and removes fraudulent or low-effort responses before they ever reach your data. Quality Guard runs automatically on every study. There's nothing to configure and no extra cost.
***
## How Quality Guard Works
Quality Guard operates at two levels: it verifies participants before they enter a study, and it scores every individual response after the interview is complete.
### Participant-Level Verification
Before a participant begins any study, Listen checks a series of identity and device signals to confirm they are who they claim to be.
* **Identity and device verification:** Signals such as device fingerprinting, IP analysis, and geolocation are checked against expected participant profiles. Suspicious patterns — like multiple accounts from the same device — are caught early.
* **Repeat respondent detection:** Listen tracks participation history across studies. If someone attempts to enter multiple studies under different identities, or exceeds participation limits, they're automatically blocked.
* **Behavioral flagging:** During the interview, Listen monitors for signs of low-effort or fraudulent behavior, including rapid tab-switching, screen reader usage that suggests AI-assisted answering, and unusually fast completion times relative to interview length.
### Response-Level Scoring
After an interview is complete, every individual response is scored automatically across five dimensions:
* **Informativeness:** Does the response actually answer the question that was asked, or is it vague and off-topic?
* **Response depth:** Is there meaningful substance in the answer — specific details, examples, reasoning — or is it a one-word reply?
* **Engagement:** Does the participant appear to be actively thinking and participating, or are they going through the motions with minimal effort?
* **Follow-up quality:** When the AI interviewer asks a probe or clarifying question, does the participant give a thoughtful, relevant response?
* **Repetitiveness:** Is the participant copy-pasting the same answer across multiple questions, or are their responses distinct and considered?
Each dimension contributes to an overall quality score. Responses that fall below the quality threshold are automatically removed and replaced with a new participant — at no additional cost to you.
***
## AI + Human Review
Not every flagged response is automatically discarded. When Quality Guard identifies a borderline interview, it's routed through a human review process before a final decision is made. This reduces false positives and ensures that legitimate participants aren't unfairly excluded because of an unusual but genuine response pattern.
***
## What Listen Does Not Allow
Listen enforces strict policies that go beyond what most research platforms require. These rules exist to protect data quality at the source — not just clean it up after the fact.
The following behaviors result in immediate removal and permanent bans from Listen's participant network.
* **Professional survey-takers:** Respondents who exhibit patterns consistent with survey optimization — such as giving strategically neutral answers, rushing through open-ends, or tailoring responses to match what they think the researcher wants to hear — are removed and permanently banned.
* **More than 3 studies per month per participant:** This limit is strictly enforced. On commodity panels, the same person may complete 40 or more studies per month, producing generic, rehearsed responses rather than genuine insights. Listen caps participation to keep responses fresh and authentic.
* **Self-reported profiles accepted at face value:** Many platforms rely on participants to honestly describe their demographics and qualifying attributes, with no verification. Listen Atlas — Listen's AI orchestration layer — verifies participants against their profile data before they enter a study, not after.
***
## Your Visibility Into Response Quality
You have full transparency into how Quality Guard has evaluated your data. Nothing is hidden or silently removed without a trace.
* **Quality indicators on every response:** In the Responses tab, each response includes a visible quality score so you can see exactly how it was evaluated.
* **Manual response management:** If you disagree with a quality decision — or want to exclude a response for your own reasons — you can manually hide any response from your analysis without permanently deleting it.
* **Screened-out response visibility:** Responses that were removed by your screener are visible in a separate view, so you can review how your screener criteria are performing and adjust if needed.
***
## Enterprise Security
Listen is built for teams that take data security seriously. The platform meets the highest standards for compliance, encryption, and data governance.
* **SOC 2 Type II certified** — independently audited controls for security, availability, and confidentiality
* **GDPR and CCPA compliant** — full compliance with global and U.S. data privacy regulations
* **Triple ISO certification** — AI Management (ISO 42001), Information Security (ISO 27001), and Privacy (ISO 27701)
* **256-bit encryption** at rest and in transit — your data is protected at every stage
* **Your data is never used to train AI models** — participant responses belong to you, not to Listen's AI systems
***
Questions about quality or data security? Email [support@listenlabs.ai](mailto:support@listenlabs.ai).
# Paying your Self-Recruited Participant Incentives
Source: https://docs.listenlabs.ai/setup-to-launch/incentives
Self recruiting requires a ton of manual payment processing to give incentives and rewards to participants. That's why we've partnered with Tremendous to make compensating your respondents easier than ever.
Our Incentives feature allows you to set an incentive amount within your study, collect participant emails securely, and send digital rewards automatically once fielding is complete — all within our platform. This article will cover how to configure your study for incentives, loading an incentive balance into your account, what a participant will receive upon study completion, and some FAQs.
Listen Labs will continue to handle incentive payments for studies we recruit. This feature applies only when you're sharing your own study link and managing participants directly.
## 1. Setting Up Incentives in Your Study
1. **Open or create your study** in Listen Labs.
2. Scroll down to the **Interview End** section.
3. Toggle on **"Reward your Respondents"** to enable incentives.
4. Set your **incentive amount** (e.g., `$50`), taking into consideration how long the study is and what is asked of a participant (e.g., video on vs. audio only) — higher incentives yield higher completion rates and faster fielding times.
![Incentive1]()
5. **Customize the email entry question text** — e.g., *"Please enter your email to receive your digital gift card for completing this interview"*
* Each participant provides the email address where their digital gift card will be sent.
* Email input is **validated**, so respondents must enter a valid address before submitting.
![Incentive2]()
6. You can also enable and edit your incentive using the Create Chat. For example, you could prompt "enable a \$50 incentive".
## 2. Loading an Incentive Balance
Before paying out the incentives at the close of your study, you'll need to load funds into your Listen Labs account.
* Each organization has an **incentive balance** that is drawn down as payments are made.
* You can **prepay** to load a balance, or do this **at the time of incentive payout**:
### To prepay:
1. Go to your "Usage & Billing" page on the left side of your Dashboard.
2. Click **+ Add Balance** and enter the amount you would like to load.
![Incentive3]()
3. Click **Pay**. You will be redirected to a Stripe page, where you can complete the payment.
### To add funds at the time of incentive payout:
1. Click **"Pay Incentive"**.
2. Click **"Insufficient Funds - Add Funds Here"**
![Incentive4]()
3. This will redirect you to your Usage & Billing page, where you can follow the same steps as above to prepay.
Once your balance is set, you'll see it reflected on your Usage & Billing page.
## 3. Paying Participants
When responses have come in:
1. Go to your study's **Responses** tab.
2. You'll see a column labeled **Incentive Status** showing which participants are eligible for payment and which have already been paid.
3. Click **Pay Incentive** to send the digital gift card.
* You can pay participants one at a time by clicking "Pay Incentive" in their respective row.
* Or, you can also pay in bulk by **selecting multiple participants** and pressing "Pay Incentives".
![Incentive5]()
4. Once paid, the incentive status will update automatically, and the participant will receive their reward via email.
## 4. What Participants Receive
Participants will get an **email from Tremendous**, our trusted payout partner, with their digital reward.
![Incentive8]()
They can choose from:
* Thousands of **gift card options** (e.g., Amazon, Starbucks, Kroger etc.), varying by region.
* Prepaid Visa card
* Donating the amount to charities
![Incentive9]()
## 5. FAQs
No — once a participant has been marked "Paid," that entry cannot be paid again.
No — the system will prevent you from paying participants that did not complete the entire study.
Payments are typically processed instantly and reach participants within minutes.
Yes, you can set a response limit on your Recruit tab within the Listen platform and thereby limit how many incentives you will end up paying out.
Yes. To customize the incentive email, reach out to your Listen Labs contact for support, or email [support@listenlabs.ai](mailto:support@listenlabs.ai).
The funds cannot be easily recovered or reissued. Please remind participants to double-check their email before submitting.
No, Listen Labs will continue to handle incentive payments for studies we recruit. This feature applies only when you're sharing your own study link and managing participants directly.
# Languages: Complete List
Source: https://docs.listenlabs.ai/setup-to-launch/languages-complete-list
Listen Labs supports transcription and analysis across 90+ languages, making it easy to conduct research with participants around the world.
**Featured Languages**
English · English (Medical) · French · French (Canada) · German · German (Switzerland) · Italian · Portuguese · Portuguese (Brazil) · Spanish · Chinese (Mandarin, Simplified) · Chinese (Cantonese, Traditional)
**All Supported Languages**
| | | | |
| ------------------------------ | ------------------------------- | -------------------- | -------------------------------- |
| Afrikaans | Albanian | Amharic | Arabic |
| Armenian | Assamese | Asturian | Azerbaijani |
| Bashkir | Basque | Belarusian | Bengali |
| Bosnian | Breton | Bulgarian | Burmese |
| Catalan | Cebuano | Chichewa | Chinese (Cantonese, Traditional) |
| Chinese (Mandarin, Simplified) | Chinese (Mandarin, Traditional) | Croatian | Czech |
| Danish | Dutch | English | English (Medical) |
| Estonian | Faroese | Finnish | Flemish |
| French | Fulah | Galician | Ganda |
| Georgian | German | German (Switzerland) | Greek |
| Gujarati | Haitian | Hausa | Hawaiian |
| Hebrew | Hindi | Hungarian | Icelandic |
| Igbo | Indonesian | Irish | Italian |
| Japanese | Javanese | Kabuverdianu | Kannada |
| Kazakh | Khmer | Korean | Kurdish |
| Kyrgyz | Lao | Latin | Latvian |
| Lingala | Lithuanian | Luo | Luxembourgish |
| Macedonian | Malagasy | Malay | Malayalam |
| Maltese | Maori | Marathi | Mongolian |
| Nepali | Northern Sotho | Norwegian | Norwegian Nynorsk |
| Occitan | Odia | Panjabi | Pashto |
| Persian | Polish | Portuguese | Romanian |
| Russian | Sanskrit | Serbian | Shona |
| Sindhi | Sinhala | Slovak | Slovenian |
| Somali | Spanish | Sundanese | Swahili |
| Swedish | Tagalog | Tajik | Tamil |
| Tatar | Telugu | Thai | Tibetan |
| Turkish | Turkmen | Ukrainian | Umbundu |
| Urdu | Uzbek | Vietnamese | Welsh |
| Wolof | Xhosa | Yiddish | Yoruba |
| Zulu | | | |
# Multilingual Voice Interviewer
Source: https://docs.listenlabs.ai/setup-to-launch/multi-lingual-voice-interviewer
Run AI-moderated voice interviews in 40+ languages with natural-sounding audio
Listen's voice interviewer reads questions aloud to participants in 40+ languages with natural-sounding audio.
For text-based translation across 90+ languages, see [**Localizing Your Study: Auto-Translations**](setup-to-launch/auto-translations)
***
## What the Multi-lingual Voice Interviewer Does
When the voice interviewer is enabled, participants hear questions read aloud. This makes interviews more accessible and conversational — particularly valuable for:
* Markets where reading in a second language creates fatigue
* Older audiences or those with lower literacy rates
* Mobile studies where audio-first feels more natural than reading
* Studies designed to feel like a natural conversation rather than a survey
***
## Choosing a Language and Voice
Listen offers multiple voice options for each of the 42 supported languages. Voices vary in tone, pacing, and regional accent — so you can choose one that feels authentic for your target audience.
*(Note: Voice audio is separate from Auto-Translations, which covers \~100 languages for text-based interviews.)*
### How to Configure Voice Settings
1. Open your study in the **Editor**.
2. Click the **settings icon** (wrench) in the left sidebar.
3. Navigate to **Language & Voice** settings.
4. Select your target language.
5. Preview available voice options and choose the best fit for your study.
6. Save your settings.
![Screenshot2026 02 25at11 15 55PM]()
Preview voices before launching. Some are more formal or informal — choose a voice that matches the register of your questions and your target audience.
***
## Supported Languages
Listen currently supports **40+ languages with voice**, including:
* **Europe:** English, French, German, Spanish, Italian, Portuguese, Dutch, Swedish, Norwegian, Danish, Finnish, Polish, and more
* **Americas:** US English, Brazilian Portuguese, Latin American Spanish, Canadian French
* **Asia-Pacific:** Japanese, Mandarin, Korean, Hindi, Indonesian, Vietnamese, and more
* **Middle East & Africa:** Arabic, Hebrew, Turkish, Swahili
The full list is in the Language Settings panel. New languages are added regularly — email [**support@listenlabs.ai**](mailto:support@listenlabs.ai) if you need a language not currently listed.
***
## Voice vs. Text Interviewer
You can use voice and text interchangeably per study, or set a study-wide default. Text tends to work better for B2B and professional audiences; voice performs better for consumer research, mobile-first studies, and international markets where reading in a second language is a barrier.
***
**Anything missing?** Let us know at [support@listenlabs.ai](mailto:support@listenlabs.ai) and we'll help you out!
# URL Parameters & Question Routing
Source: https://docs.listenlabs.ai/setup-to-launch/question-routing
Use URL parameters for tracking, integrations, and conditional question logic in your studies
Listen leverages URL parameters to manage redirects to and from our platform while preserving information such as participant IDs. This enables a number of important features within Listen, from tracking study participants to integrating with third-party tools.
*Note: This article is geared towards studies that are being manually distributed your own contact lists (e.g., self-recruited participants).* \
\
*You do not need to interface with URL parameters if you’re recruiting your study participants through Listen.*
## What are URL parameters?
URL parameters are additional pieces of information included at the end of a URL.
For example: the URL “[https://example.com/page?id=123\&lang=en”](https://example.com/page?id=123\&lang=en”) includes two URL parameters: “id” (set to “123”) and “lang” (set to “en”).
These pieces of information are useful when redirecting between websites, because they can be accessed by the website that is being redirected to. In this case, “example.com” would be able to read and react to these ID and language values.
### URL parameters in Listen
Here’s a broad overview of how URL parameters work in Listen:
* **Incoming Redirects**
When a study participant clicks on a Listen URL, all of the URL parameters are automatically collected and stored in the response data.
For example: if a participant is redirected to Listen via “[https://listenlabs.ai/s/example?id=123\&survey=external”](https://listenlabs.ai/s/example?id=123\&survey=external”), the “id” and “survey” parameters and their values (”123” and “external”) will be automatically collected and stored.
* **Manually Adding**
If you want URL parameters to be displayed in their own column on the Responses page, you can manually add them. If you don’t add them manually, they will still be displayed in a respondent's transcript, just not as their own column in the Responses table.
1. Navigate to the “Create” page in Listen, and, switch to the “Config” tab.
2. Add a URL parameter by clicking “Add another URL parameter” and entering the name of the parameter.
* **Outgoing Redirects**
At the end of a Listen interview, you can choose to redirect participants to an external URL. You can also opt to automatically add any incoming URL parameters (see above) to this URL to pass that information back to the redirect.
1. Navigate to the Edit tab on the Create page within your Listen study. Below your Questions, in the “Interview End” section, activate the “Redirect on Complete” switch.
![Ae68e991 Cd3e 46ec 8782 Cfdc436d70b6 1736195002042 Redirect On Complete Png C36bcc5a 176b 466b Bc88 82e24bd1907b 1]()
2. In the Redirect URL field, paste the URL that participants will be redirected to.
[*Note: you can also add additional URL parameters at the end of your Redirect URL. For example: both ”https://example.com?s=123” and “https://example.com?s=” are valid Redirect URLs, provided has been manually added via the above steps.*](https://example.com?s=123”)
![Ae68e991 Cd3e 46ec 8782 Cfdc436d70b6 1736195027882 Survey End 1 Png C0b2f16d 725a 40a1 B5d4 0efa2c182724]()
3. If the “Keep existing URL parameters” switch is activated, Listen will automatically ingest any URL parameters from an incoming redirect and include those as part of your Redirect URL.
*Note: the Redirect URL will still work if you include URL parameters with it. Any new parameters you add to the URL will still be included, and any duplicates will be ignored.*
![Ae68e991 Cd3e 46ec 8782 Cfdc436d70b6 1736195047673 Survey End 2 Png 3c65d6f0 53fc 4f4d 92ad Aefdcd50479f]()
## Common Use Cases for URL parameters
Now that we know how they work, let’s discuss some of the key use cases for URL parameters in Listen.
### **Tracking Individual Study Participants**
You can use URL parameters to keep track of different individuals or groups within your set of study participants to confirm completion and/or pay out incentives.
1. **Add the URL parameter**\
Go to your **Study Settings** (wrench icon on the left side of the Edit tab) and add a parameter name—e.g., `id`.
![Screenshot2025 11 05at5 21 32PM]()
2. **Create unique participant links**\
Append the parameter and value to your study URL:
```
https://listenlabs.ai/s/jeA66nX7?id=[uniqueID]
```
3. Replace `[uniqueID]` with a unique value for each participant (e.g., their email, panel ID, or contact list ID).
**Tip:** Most email sending tools (like HubSpot or Rally) can automatically generate and attach these unique IDs when sending.
1. **Track completions**\
When participants open their personalized link, Listen automatically captures and stores the ID value. You can then match these IDs against your contact list—commonly used to **confirm completion or distribute incentives**.
2. **Connect external data (optional)**\
You can upload a `.csv` file with matching ID values at the bottom of your **Details** page in Listen Labs to link participant-level data such as demographics, purchase behavior, or CRM fields.
![Screenshot2025 11 05at5 49 57PM 2]()
### **Tracking Groups of Participants**
To track groups (e.g., by market, customer segment, or recruitment source), use a group parameter instead of an individual ID.
For example:
```
https://listenlabs.ai/s/jeA66nX7?group=US
https://listenlabs.ai/s/jeA66nX7?group=CA
https://listenlabs.ai/s/jeA66nX7?group=AU
```
This allows you to compare responses across groups or set quotas. Learn more about this [here](https://support.listenlabs.ai/articles/7718788989-tracking-segmented-self-recruited-interviews-via-url-parameter).
### **Modifying Questions**
* You can use URL parameters to modify the content of your survey.
* Your study questions can be filled with the values of URL parameters.
For example, if your Participant Link is "[https://listenlabs.ai/s/xxx123](https://listenlabs.ai/s/xxx123)?productName=Example%20Product”, the question text "Why did you stop using 'productName' will be displayed as “Why did you stop using Example Product?”
![Ae68e991 Cd3e 46ec 8782 Cfdc436d70b6 1736195089568 Param In Question Png 058afed2 6080 4006 819e 0975f2d5cebb]()
* The same formatting can be used to display URL parameter values in Config fields such as “Background Info and Q\&A” to provide more context to the AI.
* You can also use URL parameters to configure **conditional display logic** on certain questions, keeping questions relevant to specific groups.
![Screenshot2025 11 05at5 14 18PM 2]()
* **Integrating With Third-Party Tools**
You can use URL parameters to redirect study participants between Listen and third-party tools. This can be useful if you want to collect data across multiple research tools for the same group of participants.
* Typically this involves redirecting a participant from the third-party tool to Listen and then back to the third-party tool. Any incoming URL parameters from the third-party tool (such as the participant ID) will automatically be preserved and included in your Redirect Link at the end of your Listen survey (see “Outgoing Redirects”).
* We also provide in-depth integration guides for common third-party tools:
* [Integrating With Decipher (Forsta)](/integrating-with-forsta)
* [Integrating With Qualtrics](/integrating-with-qualtrics)
* [Integrating With Rally](/integrating-with-rally)
### Next Steps
Now you’re ready to use URL parameters and redirects in Listen! For more detailed assistance, please reach out to our support team via [support@listenlabs.ai](mailto:support@listenlabs.ai).
# Quotas
Source: https://docs.listenlabs.ai/setup-to-launch/quotas
Use recruitment quotas to balance your participant sample and control who gets in
Quotas are an advanced tool for keeping your respondent mix balanced. Once a quota is full, Listen automatically screens out any additional candidates who fall into that segment.
Most studies do **not** need quotas. Natural fallout after the screener usually mirrors your target audience. Reach for quotas only when you have clear goals such as “ ≥ 20 % paid users” or “ ≤ 50 % companies under \$1 B.”
**How Quotas Work**: After a respondent answers screener questions, the platform checks whether admitting them would satisfy or violate your quotas. If they satisfy all requirements, they're let in — otherwise they're rejected. Think of quotas as a soft extension of the screener.
**Quota Types**:
* **Maximum**: "At most X participants from this segment." Once the cap is reached, further candidates from that group are screened out.
* **Minimum**: "At least X from this segment." When admitting a non-qualifying respondent would make the minimum impossible to reach, they're rejected.
* **Exact**: Combines a minimum and maximum. Use only when the split is essential, as it increases screen-outs.
**Absolute vs. Relative Quotas**:
* **Absolute**: Fixed numbers (e.g., exactly 15 paid users)
* **Relative**: Percentages (e.g., 30%). The platform translates the percentage to an absolute figure based on your response limit — and scales automatically if you raise the limit later
### Pro Tips
* **Use maximum quotas when in doubt**: They're easier to understand and lead to fewer screen-outs than minimum quotas
* **For multi-select questions**: Minimum quotas can be useful to ensure coverage of all answer options
* **Advanced segments with min-quotas**: If combining multiple questions or URL parameters in an advanced quota, either use max quotas, or make sure correlated segments are in the same group
* **If your study keeps pausing**: Go to the Responses tab, filter for "Screened out responses," and check the "Screen out reason" column to diagnose which quota is causing the issue
### Quick Reference
| Quota Type | When to Use | Effect |
| ----------- | ------------------------------------------------- | ------------------------------------------ |
| **Maximum** | Cap a segment (e.g., "≤ 30% under 25") | Screens out once cap is reached |
| **Minimum** | Ensure coverage (e.g., "≥ 10 ChatGPT users") | Screens non-qualifiers when min is at risk |
| **Exact** | Require a precise split (e.g., exactly 50% women) | Highest screen-out rate — use sparingly |
***
## How to Set Up Quotas in Listen
### Step 1: Write Screener Questions First
Quotas reference screener question answers (or URL parameters). Before setting up quotas:
1. Write your screener questions with clear answer options
2. Each answer option will become a potential quota segment
3. Learn more about [setting up screener questions](/setup-to-launch/screener-questions)
### Step 2: Set the Total Response Limit
1. Navigate to the **Quotas** tab in your study
2. Set your **Total Response Limit** (e.g., 50 completes) — this is required before adding quotas
3. This is the maximum number of completed responses your study will accept
### Step 3: Add a Quota
1. Click **Add a quota** (or **Advanced Configuration** for multi-question segments)
2. Choose the screener question (or URL parameter) you want to quota on
3. Define segments — the answer options that form each group
4. Select a rule: **Minimum**, **Maximum**, or **Exact**
5. Set the count or percentage for each segment
**Example — Maximum quota:** "At most 10 participants under 25 years old." Once 10 completes are in that age band, further under-25 candidates are screened out.
**Example — Minimum quota:** "At least 10 ChatGPT users." When admitting a non-ChatGPT user would make the minimum impossible to reach, they are screened out.
### Step 4: Advanced Quota Configuration
For quotas based on a combination of multiple questions or URL parameters:
1. Click **Advanced Configuration** at the bottom of the Quotas tab
2. Build segment combinations (e.g., "male & married", "female & single")
3. Use **maximum quotas** when combining multiple attributes — minimum quotas won't work as expected for complex combinations
### Step 5: Debugging a Paused Study
If your study pauses automatically, it's usually because:
1. **Response limit reached**: The study is full
2. **Too many screen-outs**: 100 consecutive screen-out responses
3. **Low incidence rate**: Less than 10% of responses qualify
**To diagnose:**
1. Go to the **Responses tab**
2. Clear the "complete" filter
3. Switch to "Screened out responses" on the left
4. Check the "Screen out reason" column
**To fix:**
* **If screener rejection is too high:** review and relax screening criteria, or contact support for a custom recruitment quote
* **If quota limits are causing rejections:** loosen quotas on less important segments, or update recruitment filters to match current quota needs (e.g., if your 65+ quota is full, set age filter in recruitment to ≤65)
***
**Anything missing?** Let us know at [support@listenlabs.ai](mailto:support@listenlabs.ai) and we'll help you out!
# Recruiting 101
Source: https://docs.listenlabs.ai/setup-to-launch/recruiting-participants
Find the right people for your study using Listen's panel, your own participants, or both
The Launch tab is your command center for getting the right people into your study. Whether you're using Listen's global panel, bringing your own participants, or combining both — this guide walks you through everything from targeting to launching.
***
## Your Recruitment Options
Listen connects to a network of 30M+ verified global respondents across 45+ countries and 100+ languages from top-tier white-label qualitative panels. Define your target audience in the Launch tab, and we'll find and qualify matching participants automatically.
If you have an existing customer list, community, or employee panel, distribute your study via **Direct Link**. Participants click your link, complete the study, and their responses are collected automatically.
* You control outreach and incentives
* Listen handles the interview and analysis
* Use URL parameters to track individual participants (see the [URL Parameters](/setup-to-launch/question-routing) article)
Run multiple recruit groups within a single study — for example, one from Listen's panel and one from your own customer list. This is ideal for multi-market studies or when comparing internal and external audiences.
***
## Defining Your Target Audience
* **Demographics:** Age, gender, household income, employment status.
* **Geography:** Country, region, or city.
* **Professional attributes:** Job title, seniority, industry, company size (Professionals panel).
* **Behavioral targeting:** Handled via screener questions inside your study.
***
## General Population vs. Professionals Panel
### **General Population Panel**
The General Population (B2C) panel is Listen's default. Use it for:
* Studies targeting everyday consumers based on behavior, demographics, or category usage
* Research into personal or household purchasing decisions
* Creative testing, brand perception, and consumer UX
* Studies that need scale and speed — general population fills faster
## **Professionals Panel**
Use the Professionals panel when your audience is defined by their professional context. Ideal for:
* B2B research targeting specific job functions or industries
* Studies on business software, enterprise tools, or workplace decisions
* Healthcare professional research (physicians, nurses, pharmacists)
* Studies requiring decision-maker access (C-suite, budget holders)
### **Considerations**
* Higher cost per complete reflects premium on professional audiences
* Slower fielding for very niche targets
![Screenshot2026 02 25at11 28 40PM]()
For highly specialized targeting (niche healthcare, less than 1% incidence rate, enterprise C-suite), contact [**project@listenlabs.ai**](mailto:project@listenlabs.ai) for managed recruitment support.
***
## Setting a Response Limit & Quotas
Set a **Response Limit** before launch — the maximum number of completes you want to collect. Required if you're using quotas. Once the limit is reached, the study closes automatically.
You can use the response limit to run a **soft launch** of your survey. For example, if your target N=100, then you can set your response limit to N=10, and your recruitment will automatically pause. Then you can analyze your responses and make any adjustments to your guide.
Quotas control the demographic or behavioral composition of your respondent pool. See the [Recruitment Quotas](/setup-to-launch/quotas) article for full setup instructions.
***
## Launching
1. Review your targeting settings and response limit.
2. Click **Launch** at the top right of the Launch tab.
3. Your study is live and begins collecting responses immediately.
You can pause or close your study at any time from the Launch tab without losing any collected responses.
***
## Monitoring Responses
* Watch responses arrive in real time in the **Responses** tab
* Click into any response to view the full transcript and video
* Export responses at any time to CSV, Excel, or Google Sheets
* Filter by theme, screener answer, or keyword
***
Need help with recruitment strategy? Email [**support@listenlabs.ai**](mailto:support@listenlabs.ai).
# Screener Questions
Source: https://docs.listenlabs.ai/setup-to-launch/screener-questions
Screeners questions (or screeners) filter participants before your study begins, so you only hear from the people who matter. This guide covers what they are, when to use them, how to set them up in Listen, and how they connect to incidence rate; a key cost factor in research.
## What Are Screening Questions?
Screening questions qualify or disqualify respondents from your survey based on their answers. They help you target your audience more precisely and filter out participants from a broader sample who aren’t a fit.
**Example:** Imagine you’re launching a new streaming service designed for heavy TV and movie watchers. You might start with a screener like:
*“How many hours per week do you typically spend watching TV shows or movies (streaming or live)?”*
* 0–2 hours
* 3–5 hours
* 6–10 hours
* 11+ hours
If your goal is to hear from frequent watchers, you could set your study to only continue for respondents who select *6–10 hours* or *11+ hours,* rejecting those who select *0-2 hours* or *3-5 hours*.
***
## Benefits: Why Use Screening Questions?
* **Reach your target audience.** Only qualified participants enter your study
* **Save time and cost.** Filter out unqualified respondents before they take your full study and prevent fraud.
* **Improve data quality.** Responses come from participants who are relevant to your study.
* **Enhance the respondent experience.** Participants aren’t asked questions they can’t answer.
***
## How to Set Up Screeners in Listen Labs
1. **Add a screening section to your study.** In your study editor under the “Create” tab, press +Add Screening Section if you don’t have one already.
2. **Click +Question in your screening** **section** to add a new screener, then write your question.
3. **Write your qualifying criteria.** Use clear answer choices that map directly to your inclusion or exclusion rules.
4. **Apply logic.** Mark which answers should qualify or disqualify a respondent.
![Screenshot 2026 03 20 At 12 06 36 PM]()
* For **single-select questions**, this will be either:
* Accept: participants that choose this option will advance.
* Reject: participants that choose this option will not advance.
* For **multi-select questions**, answer options will be either:
* Accept: participants MUST select an Accept option to continue.
* May Select: participants can select these options, but also must select an Accept option to advance.
* Reject: no matter what, participants who select these options will not advance, regardless of what else they choose.
5. **Test your flow.** Preview the survey using the preview link to confirm participants are routed correctly.
6. **Check how your screeners are impacting fielding.** Go to the **Responses** tab and filter for *“Screened out responses.”* to see how many participants attempted your study but were disqualified, and for which screener question, be sure to untick *“Complete”* on the upper right side.
![Screenshot2025 10 21at5 08 22PM]()
## Incidence Rate: How Screeners Affect Cost
Survey screening questions connect directly to an important research concept: **incidence rate (IR).**
* **Definition:** The incidence rate is the percentage of respondents who pass your screening questions and go on to participate in your survey.
**Why it matters:**
* Every screener you add narrows your potential audience, lowering your IR.
* High IR (lots of respondents qualify) → lower cost per completed survey.
* Low IR (few respondents qualify) → higher cost, because you must screen many participants to find those who fit.
**Example:**
* If 40 out of 100 respondents qualify, your incidence rate is 40%.
* If only 5 out of 100 qualify, your IR is 5%, meaning you’ll need to invite far more people, which increases costs and slows down fielding time.
***
## Best Practices For Screeners
**Be specific.** Ask targeted questions (e.g., *“In the past month, how many hours per week have you spent streaming TV or movies?”* rather than *“Do you watch TV?”*).
**Disguise your screeners and avoid yes/no questions.** Make sure your qualifying logic isn’t obvious. Avoid telegraphing what the “right” answer is— for example, instead of asking *“Do you subscribe to Apple TV+?”* directly, include it as one option in a broader list of services and ask which they subscribe to. Also be sure your Study Title and Welcome Message don't give away the passing screener answers.
**Funnel from general to specific.** Start with broad questions (e.g., *“Which of these streaming services do you currently subscribe to?”*) before moving into more detailed ones (e.g., *“How often do you watch original content on Apple TV+?”*). This flow feels more natural to respondents and prevents disqualification from seeming abrupt.
**Keep it simple.** Don’t use industry jargon or overly complex recall questions.
**Balance precision with practicality.** Too strict criteria can lower your IR and drive costs up significantly. Focus on the factors most critical to your research, and consider proxy audiences when possible (e.g., instead of only screening for people who *subscribed to Apple TV+ in the past month for a specific show*, consider broadening to people who *subscribe to any niche streaming service* or *regularly watch exclusive original content*).
* If your fielding is slow, examine which screeners are filtering the most people out and consider expanding.
***
## When to use Screeners vs. Recruitment Criteria
When recruiting using Listen's platform, broad demographics like age, gender, or household income can usually be handled in your recruitment settings. When participants join the panel, they are asked a set of general demographic questions (called pre-screeners), allowing us to target our outreach without needing to explicitly ask every question.
More specific criteria—such as which brands someone uses, how recently they purchased a product, or detailed behaviors— should be asked as screener questions inside your survey.
***
## Using Screeners to Set Quotas
Screeners don’t just decide *who* qualifies— they also **define the groups you’ll track if you are setting recruitment quotas**. For example, if your screener asks about age, you can then set quotas to balance your sample across age brackets.
📖 Learn more about using quotas in our **Guide to Using Quotas.**
***
## Summary
Screening questions ensure your survey results come from the right people. They not only improve data quality and participant experience but also determine your **incidence rate**, which directly impacts study cost and fielding times. By placing screeners up front and following these best practices, you’ll save costs, improve your data, and deliver a better experience for participants.
***
**Anything missing?** Let us know at [support@listenlabs.ai](mailto:support@listenlabs.ai) and we'll help you out!
# Study Design 101
Source: https://docs.listenlabs.ai/setup-to-launch/study-design-101
### Getting Started
After logging into Listen Labs, you'll be brought to your Workspace dashboard page.
This central hub displays all your existing studies. Here, you bird's-eye view of all your research projects in one place, allowing for efficient project management.
You can also use the "Create Folder" to help keep your studies organized!
![Screenshot 2026 03 19 At 5 48 44 PM]( "Screenshot 2026 03 19 At 5 48 44 PM")
![Screenshot 2026 03 19 At 5 48 44 PM]( "Screenshot 2026 03 19 At 5 48 44 PM")
## Step 1: Creating Your Project
1. Click on **New Study** from your dashboard to begin your research journey
2. You'll be taken to the "Tell us about your project" page, part of our Create function. Here you should provide comprehensive details about:
* **Project Background**: Context that helps the AI understand your research needs
* **Company Information**: Details about your organization to personalize the interview experience
* **Study Objectives**: Specific insights you hope to gather, which guides the AI's questioning strategy
* **Hypotheses**: Key assumptions you want to test, helping the AI probe in the right areas
3. Click the arrow to proceed to the discussion guide creation phase
*Tip: Your initial prompt from is the foundation of your study. Listen Labs' AI uses it to auto-generate your study goals, screener, recruitment criteria, respondent format, and discussion guide. These objectives are also used later to shape your analysis report, so the more specific your prompt, the more targeted your insights.*
**Time-Saving Alternative**: If you already have a discussion guide, upload it directly and the AI will intelligently parse it, saving you setup time
![Screenshot 2026 03 19 At 5 53 36 PM]( "Screenshot 2026 03 19 At 5 53 36 PM")
![Screenshot 2026 03 19 At 5 53 36 PM]( "Screenshot 2026 03 19 At 5 53 36 PM")
## Step 2: Build Your Discussion Guide with the Study Composer
In this section, you'll collaborate with Listen's AI "Study Composer" to create a structured yet dynamic discussion guide
![Screenshot 2026 03 19 At 6 13 01 PM]()
* **Your AI-Generated Study Set Up**: Your initial prompt in Step 1 formed the foundation of your study.
* Inside **Study Composer**, you will co-create your Discussion Guide.
* At the top, review your auto-generated **Study Goals** and **Audience** -- edit these directly if needed
* Prompt the AI or make manual inline edits anywhere in the guide; changes preview in real time
* Click **Export** to download a .docx copy of your discussion guide at any time
* **Interactive Chat Interface**: Use the intuitive chat function on the \*\*left \*\*to refine your guide
* The guide updates in real-time as you chat with the AI, allowing for iterative improvements
* You can undo any edits by clicking the "Undo / Redo" buttons at the top of the page
* Simply type natural language commands to shape your guide. For example:
* **"Add demographic screener questions"**: Inserts pre-validated screening questions to ensure you're reaching the right audience. (More on screening [HERE](https://support.listenlabs.ai/articles/4374293584-using-screener-questions))
* "**Add a concept test"**: Creates a structured section for evaluating products, advertisements, or other stimuli with consistent metrics
* **"Edit question wording for question X"**: Refines question language for clarity or to address specific research needs
* **"Rearrange questions for flow"**: Optimizes the flow of your interview for better participant experience and data quality
* **"Add follow-up probes to question X"**: Ensures the AI digs deeper on critical topics to uncover insights
![Screenshot 2026 03 20 At 11 19 43 AM]()
**Automatic Estimations**:
* **Length of Interview (LOI)**: The system calculates approximately how long each interview will take, helping you plan participant incentives and manage expectations
* **Response Format**: Shows how participants will interact with your questions, ensuring you get the data format you need (editable in Settings)
* **Recruitment Group**: Creates a recruitment audience based on the profile criteria described (editable in the Recruit/Launch tab)
* When you're satisfied with your guide structure, click **Configure Study** to move to detailed customization in the **Editor**.
## Step 3: Configure, Edit & Preview
Your Discussion Guide will remain the central view in your screen. It will be broken out by Question Blocks which you can manage and edit directly, or through the chat.
![Screenshot 2026 03 19 At 6 14 47 PM]()
* **Left Pane**: the Interactive Chat can be brought in and out of view by clicking the small chat symbol
![Screenshot 2026 03 20 At 11 24 58 AM]()
* **Right Pane**: Preview the interview from respondent POV. You can test your screener logic and probes for individual questions, in the lens of a respondent, by selecting "Start video interview" at the bottom of the right hand side of the page
![Screenshot 2026 03 19 At 7 09 58 PM]()
* **Question Management**
* **Question Types**: Select from various formats (open-ended, multiple-choice, rating scales, etc.) to collect the right type of data for each research question
* **Question Visibility**: Toggle the arrow next to each question to expand/collapse details, making navigation of complex guides easier
* **Follow-up Control**: Adjust the number of AI follow-up questions to balance depth vs. interview length.
* **Probe Configuration**: Add specific probing instructions in the "Other Instructions" field to guide the AI on exactly what aspects to explore further
* **Question and Section Organization**: Use the dots to move questions and sections for optimal interview flow, or tell the Chat to make question flow changes
* **Question Actions**: Delete questions by selecting the trash can
* **Duplication**: Select the two papers icon to make duplicates / copies of a specific question
* **Advanced Features**
* **Media Integration**: Drag and upload static images or videos
* **Website Embedding**: Embed URLs directly within questions
* **Conditional Logic**: Create sophisticated question branching based on previous multiple choice / closed ended responses
* **Run from start**
* Use the center "Run from start" button to test your interview as a real respondent while having access to editing the questions and probes as you go
* Your answers from previous questions will not be saved if you click into any individual question once starting
* You will not be able to preview any randomization for concept testing within this function (This function is available within the "Open Preview" - which is a true respondent experience that will open in a new window)
### Quick Reference
**Question Types**:
* Open-ended: Best for exploratory research and deep insights
* Single select: When you want one clear answer from a list
* Multi-select: When multiple answers are possible
* Ranking: When you want respondents to compare options
**Follow-up Levels**:
* **None**: No additional questions beyond the main question
* **On short answers**: Only if response is a few words
* **1 follow-up**: Light probing
* **2-3 follow-ups**: Deeper exploration
***
## Step 4: Configure Study Settings
In the Editor, access **Study Settings** (wrench icon on the left) to configure:
1. **Language Settings**: Set participant-facing languages and reporting language
2. **Study Presentation**: Add a title participants will see and an introduction brief
3. **Translations**: Enable multi-language support for global studies
4. **URL Parameters**: Add custom parameters for tracking or integrations
5. **Markdown Formatting**: Enable rich text formatting in question text
**Anything missing?** Let us know at [support@listenlabs.ai](mailto:support@listenlabs.ai) and we'll help you out!
# Visual Insights
Source: https://docs.listenlabs.ai/setup-to-launch/visual-insights
## What it is
**Visual Insights** gives Listen a read on what participants actually do on screen, like where they click, what they navigate to, what they skip, instead of relying only on what they say out loud and a passive screen recording requiring extensive manual review. \
\
That on-screen signal does two jobs: it sharpens the interview, and it carries into analysis.
In the moment, the Listen Interviewer can ask follow-ups based on what was said and done together, including where the two don't line up. After the interview, that same on-screen behavior becomes a signal the report and analysis can read across every session and surface trends, gaps, and contradictions between what people said and what they actually did, and becomes completely queriable with the Research Agent chat.
It's steered by your study goals throughout. Whatever you tell it to care about, it's more likely to watch for live and look out for it in the Report. Say your goal flags that you care about search methods: if a participant types a weirdly specific query, the Interviewer is more likely to ask why they searched it that way in the moment, and that behavior is more likely to surface when the report gets built.
## What it does + when it's useful
*In the interview:*
* **Probing on observed behavior.** A participant uses some filters but not others. The moderator asks why they chose the filters they did, and they explain they use hard filters for the things they're strict about (size, price) and leave the rest open to browse on vibes. Steered by your study goals, so if you flagged that you care about how people navigate or filter, it's more likely to dig in there.
* **Catching say-do gaps.** A participant says early on that they care a lot about reviews when picking a product. Then on screen, they pick a pair of trainers without ever opening the reviews. The moderator catches the disconnect and asks why (it turns out there weren't enough of them to feel trustworthy). That's an insight you'd completely miss if Screen Observation didn’t catch the action and probe on it.
* **Recovering off-track sessions.** Tale as old as time in unmoderated/AI-moderated testing: someone gets ahead of the instructions or lands on the wrong thing, and the whole session becomes useless. Now, if a participant is doing a running-shoes task but goes to Nike and picks Air Jordans, the moderator says "Can you find running shoes instead?" and gets them back on track. It also handles the small stuff like "I don't know if I'm screen sharing right now," and keeps people moving.
*In analysis:*
After the interview, the on-screen behavior gets turned into a timestamped, written record of what happened on screen, like a parallel transcript running alongside the spoken one. It synthesizes the spoken transcripts and the on-screen behavior to tell a unified story, calling out behaviors that support or contradict spoken responses, flagging notable trends, and so forth. \
\
The report and chat agents can use Screen-observed behavior in the same way they use a normal spoken transcript: you can query it, quantify it, and pull it into the report any way you like, giving researchers many ways to explore, compare, and validate their data.
## An example: Music streaming app study
\
The task was to build a playlist of five songs for someone they love. \
\
**87% of participants rated the task "easy" or "very easy."** But their on-screen behavior told a different story: across sessions, only a handful actually added all five songs in the task window despite all saying they completed it, and 28% displayed meaningful navigation frictions (opening and closing menus, backtracking, etc.) along the way. For those that did complete the full task, it took 6-10 minutes, much longer than the expected \~4.
And it's all traceable back to what people actually did. From the "28% experienced navigation frictions" metric, you can drop into the behavior underneath it: which participants it happened to, what the snags were, and from there jump to the exact timestamp, open that moment in their screen recording, and watch it happen for yourself (the same UI you use across the Listen analysis suite today).
You can also ask the Research Agent chat about their on-screen behavior, things like "how many people hit navigation confusion," "create a highlight reel of people who said X but did Y," and it'll pull it together.