UserTold

Lists configured interview studies and usability tests by title, research topic, or status. Returns newest-first summaries and studyRef values for studies.get or studies.get_results. For recorded participant interviews, use interviews.list. Full scripts and page placement are in studies.get.

studies.list

Lists product problems and improvement opportunities collected from interviews. Returns paginated Findings with priority and supporting Interview/Evidence counts. Closed Findings are hidden by default; findings.get_evidence returns their sources.

findings.list

Lists recorded participant Interviews for review, download, or processing checks. A projectRef is sufficient. Returns paginated summaries and interviewRef values for context, artifact, and processing tools. Supports Study and Interview status filters and omits participant identity fields.

interviews.list

Searches interview Evidence for user problems, needs, workarounds, or successful experiences. Returns paginated quotes, observations, and source references for review or grouping into Findings. Defaults to product_under_test; target_surface="all" includes other areas.

evidence.list

Returns the project widget snippet, saved installation verification, and interview readiness. Install once across the website; page and language rules select the active interview study. Does not run a new verification.

projects.get_widget_setup

Creates a private backlog Finding from reviewed Evidence and calculates priority. Mark it ready only after source review. Does not create a GitHub or Linear issue.

findings.create_from_evidence

Returns one Evidence observation with its quote, observed behavior, interpretation, source interview and timestamp, page context, review state, and linked Findings. interviews.get_context provides the surrounding moment.

evidence.get

Returns a limited transcript window and sanitized navigation/click events around timestamp_ms. Check truncation flags; interviews.get_artifacts provides the complete transcript and recordings.

interviews.get_context

Use when planning customer discovery, user interviews, usability tests, concept testing, or research into onboarding, churn, pricing, and feature feedback. Pass the user's goal in their own words. Returns guidance grounded in UserTold documentation; saves requests and responses for service improvement without changing projects or studies. For existing research results or an exact operation, use the relevant tool directly.

setup.recommend

Returns a Study's script, goals, invitation, page and language placement, websites, and existing recruitment link. If scriptOmitted=true, retrieve the full script through the dashboard or CLI.

studies.get

Queues an authorized bug report or suggestion about UserTold to its team. The report cannot be recalled. Not for feedback about the user's product. Exclude credentials, personal data, and raw private content.

feedback.submit

Starts a new processing attempt after interviews.processing_status shows a durable failure or no progress for 24 hours. Replaces generated Evidence and preserves manual Evidence. If the outcome is uncertain, check status and do not retry automatically.

interviews.retry_processing

Returns existing Study results with interview counts, supporting quotes, source references, related findings, and uncertainty. Follow continuation offsets for omitted records; use evidence.get or interviews.get_context for individual moments. Does not generate a new synthesis.

studies.get_results

Sends an authorized reviewed Finding with linked Evidence to GitHub or Linear. Creates and returns an external issue, or returns the previously recorded issue. Omit provider for the configured destination; pass "github" or "linear" only as an explicit override. The issue cannot be recalled.

findings.send

Update a Study returned by studies.list or studies.get, including its canonical Invitation, Visibility, and customer origins. Set invitation to null for the built-in Invitation or allowedOrigins to [] to stop publishing its direct-link campaign URL. Set status to active to start new interview collection; set status to closed to stop new interviews without interrupting an interview already in progress. The install-once Project widget selects active Studies through Visibility and Invitation, so no per-Study snippet or separate launch/stop call is needed; projects.get_widget_setup remains the sole snippet source.

studies.update

Use before saving a new or revised interview flow with studies.create or studies.update. Validates the supplied StudyScriptV2 and returns errors or a summary of steps, goals, and modes. Does not save or activate a study; no project is required.

studies.validate_script