UserTold.ai
Open appGet Started

Studies

A study defines the goals and ordered interview segments used for participants.

Every new Project starts with one active First user interview. It is a generic discovery conversation with no Intake, reward, or placement restrictions. Install the Project snippet first; editing this starter is optional, and Web, REST, CLI, and MCP all update the same Study.

The Study Design Guide covers design decisions, mode selection, and a complete example.

Create a study

Choose New study, then pick what kind of encounter you want: observe ordinary use, test a feature or task, or invite an open conversation. That choice is separate from the three segment modes below. Add goals and the shortest segment sequence that supports them.

Use the three participant-facing modes:

  • 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, run 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

Three checks answer different questions:

CheckSurfaceWhat it verifies
Study readinessThe Go live section of a studyLists what still blocks publishing — Missing goals, Missing script, No debrief segment, or an intake that is not ready.
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 checkWebsite interviews setup, usertold project verify-widget-installation, or projects.verify_widget_installation in MCPAn exact public HTTPS page checked for the canonical loader and Project key, then 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

Under How participants arrive, choose On-site Invitation or Recruitment link. For an on-site Invitation, also choose Launcher only or Open when eligible. The optional panel carries copy, duration, CTA, and one exact reward; Minimize and Hide stay remembered. List every origin the widget runs on under Interview websites in the study's Go live section.

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 activationOpen the study's Go live section and fix the item it names — goals in Research goal, a missing debrief in Interview flow, the intake in Participants.
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 origin under Interview websites in the study's Go live section, or leave the list empty while testing.

Continue