Studies

A study defines the goals and ordered interview segments used for participants. This page covers creating, linking, activating, and troubleshooting a study in UserTold.

The Study Design Guide is the canonical home for design decisions, mode selection, and a complete example.

Create a study

Choose Create Study, then a mode: observe use, test a feature or task, or invite an open conversation. Add goals and the shortest segment sequence that supports them.

Use the three participant-facing modes deliberately:

  • talk conducts a conversation and follows up on participant answers.
  • speak delivers a scripted instruction or transition.
  • observe silently captures product use for later interpretation and debrief.

For a task-based study, a dependable sequence is an instruction, silent observation, a planned debrief, and a closing message. Validate the script and run it yourself before inviting participants.

Know which check you are running

UserTold keeps three checks separate because they answer different questions:

CheckSurfaceWhat it verifies
Study readinessStudy dashboardGoals, participant journey, planned debrief, linked intake, and activation prerequisites for the stored study.
Script validationDashboard save, usertold study validate-script, studies.validate_script in MCPScript structure and runtime-safe fields for each segment mode. It does not grade research quality or inspect a website.
Website integration checkStudy security settings, usertold project verify-widget-installation, or projects.verify_widget_installation in MCPChecks an exact public HTTPS page for the canonical loader and Project key, then inspects HTTP and meta CSP plus Permissions-Policy. It does not execute the host app, grant browser permissions, or replace a human browser smoke test.

Link the study to an intake so qualified participants enter the intended interview. When linked:

  • qualification routes the participant to this study;
  • the widget loads this study's active script;
  • the interview retains its intake response context.

Activate both the study and intake before testing the participant flow. If either is paused, a qualified participant cannot begin the intended interview.

Configure the embed context

Choose Launcher only, Open when eligible, or Open from recruitment link. The optional panel owns copy, duration, CTA, and one exact reward; Minimize and Hide stay remembered. Allow every embed origin.

For a human-moderated consumer interview, $80/hour is a marketplace benchmark. AI-moderated or short in-product interviews usually require a smaller fixed reward. State the participant's actual fixed amount, for example: “20 minutes · $25 gift card.” Eligibility and delivery terms are optional; there is no calculator or fulfillment.

See Study Runtime for advancement and recovery.

Test before inviting participants

Complete one interview through the same intake and embed your participants will use. Confirm that:

  1. qualification opens the intended study;
  2. instructions fit the product task;
  3. observe segments advance through a deterministic completion rule or time limit;
  4. a planned talk segment debriefs the observed task;
  5. the interview completes and produces a reviewable source record.

Troubleshooting

SymptomNext action
Study readiness blocks activationResolve the specific goals, journey, debrief, or intake item shown in the study dashboard.
Script validation failsCheck the required structure and mode-specific fields in the Study Design Guide, then use the dashboard save error, CLI result, or MCP response.
Website integration check stops at PageMake the exact page publicly reachable with HTTP 2xx. Loader, key, CSP, and Permissions-Policy checks are intentionally skipped when the page itself cannot be fetched.
A qualified participant cannot startConfirm the intake is linked to this study and both are active.
An observe segment never advancesAdd an appropriate deterministic completion rule and a time limit.
The debrief is genericPut a planned talk segment after observation and connect it to the task and study goals.
Evidence is thinInspect the transcript and timeline, then sharpen the task, goals, or planned debrief.
The widget reports an origin problemAdd the embed origin to the study settings, or leave the allowlist empty while testing.

Continue