Quickstart

Four steps to your first AI interview.

Fast path

1. Authenticate

npm install -g usertold

usertold auth login

2. Create a project and study

usertold init --name "My Product" --format json --yes

3. Select the project

usertold project list
usertold project use <orgHandle>/<projectHandle>

4. Embed the widget and activate

Copy the snippet from the intake's Embed Code section into your product, then activate the intake and study from the dashboard or CLI.

That's it — qualified participants can start in-product interviews from your widget.

Get from zero to your first AI interview in under 10 minutes.

Prerequisites

  • A UserTold.ai account — sign in with Google
  • That's it — no API key required to start. By default, interviews and evidence extraction run on UserTold's platform OpenAI key, metered to your prepaid credits, with a small free allowance for new accounts. Using your OpenAI API key is optional (see step 2).

Choose Where to Start

The dashboard, CLI, MCP, and REST API all work with the same project. Start with the tool that fits the job:

SurfaceUse it for
DashboardCreate and review studies, inspect interviews, replay source context, connect trackers, and make visual decisions.
CLIRepeatable setup, scripts, CI jobs, transcript import, media upload, export, and bulk evidence/work operations.
MCPClaude, Cursor, Codex, or another agent that needs project-aware tools, resources, and prompts in one protocol.
REST APICustom product integrations, backend jobs, webhooks, and anything that needs exact request/response schemas.

The fastest first run is usually Dashboard or usertold init. After that, the CLI can use the project's orgHandle/projectHandle reference, and MCP can use the project ID or a unique project handle.

1. Create a Project

After signing in, create a project from the dashboard. A project maps to one product or product area you want to research.

2. (Optional) Use your OpenAI key

By default, UserTold runs interviews and evidence extraction on its platform OpenAI key — metered per token against your prepaid credits, with a small free allowance so new accounts can start immediately. You can skip this step.

To run inference on your own provider instead, add your OpenAI API key in Project Settings:

  • When you use your OpenAI key (BYOK / Bring Your Own Key), inference is billed directly to your OpenAI account — UserTold doesn't bill it
  • Keys are encrypted at rest, scoped per project, and kept out of logs
  • You can remove or rotate the key any time from Project Settings

See the pricing page for metered usage and the Security page for key handling.

3. Create a Study

A study defines what the AI should explore. Go to Studies and create one.

Add goals, then define Talk, Observe, and Speak segments for each phase of the interview. See Studies for configuration details.

4. Create an Intake

An intake qualifies participants before they enter an interview. Go to Intakes and create one.

Add qualification questions — for example:

  • "How often do you use [product]?" (single choice)
  • "What's your role?" (single choice)

Set rules to auto-qualify or disqualify based on answers. Link your study to the intake so qualified participants enter the right interview.

5. Embed the Widget

Add the widget to your product. Open your intake's detail page and copy the embed snippet from the Embed Code section:

<script
  async
  src="https://usertold.ai/v1/widget.js"
  data-project-key="ut_pub_YOUR_KEY"
  data-screener-id="your-screener-handle"
></script>

The loader waits for your page to finish loading before fetching the widget, so it never slows down your own content. Use https://usertold.ai for the widget script itself. The dashboard where you copy this snippet remains at https://app.usertold.ai.

Your project key is in Project Settings under SDK Key. The data-screener-id attribute takes your intake's handle — the human-readable slug on the intake detail page. (The embed attribute and API still use the name screener, the internal name for an intake; they refer to the same thing.)

The widget appears as a floating button. When users click it, they see the intake, and if qualified, start the interview — all within your product. See Widget Integration for customization options.

6. Run Interviews

Activate your intake and study. Participants who visit your product will see the widget, answer the intake, and if qualified, start an in-product interview.

The study script controls the engagement pattern: talk for conversation, observe for silent product-usage capture, and scripted speak for instructions, transitions, and thanks.

7. Review Results

After each interview completes, UserTold.ai automatically:

  1. Transcribes the recording
  2. Extracts evidence (struggling moments, desired outcomes, workarounds, etc.)
  3. Groups related evidence into review packets with priority context
  4. Links each packet back to its source evidence for verification

Check the Interviews page to see transcripts and recordings. Check Evidence to see extracted insights. Check Work to see evidence review packets waiting for source review.

8. Push to Your Tracker

When a review packet has been verified and promoted to delivery work, UserTold.ai can push it to your issue tracker:

  1. Go to Project Settings and connect your delivery tracker
  2. Open the review packet and verify the linked quotes, transcript or playback context, grouping fit, and intended product area
  3. Move the verified work item to Ready
  4. Push the work item to Linear or GitHub so the issue carries the source evidence

For Linear issues, completion sync can resolve the current linked evidence. Future interviews are still watched for similar evidence that may resurface for recurrence review.

Your First Complete Run

Use this as the completion checklist for your first run:

  1. Project exists — Dashboard shows the project, or usertold project list --json returns its project_ref.
  2. Study is active — The study has a valid script and status: active.
  3. Intake is active and linked — Qualified participants route into the study.
  4. Widget loads — The launcher appears after your page finishes loading.
  5. Interview completes — The interview appears under Interviews with transcript, recording, or processing state.
  6. Evidence is available — Evidence cards appear, or the processing result clearly says no evidence was found.
  7. Verify the source — Check the quote, transcript or replay, page path, and grouping.
  8. Prepare the work — Create or review a work item tied to the evidence.
  9. Push verified work — Send the item to Linear or GitHub with source evidence attached.
  10. Close the loop — When the linked issue is done, UserTold can resolve current evidence and watch for recurrence.

Do not skip step 7. Verification is the step that turns a useful evidence packet into work worth shipping.

For Agents: Non-Interactive Setup

All of the above can be automated via CLI with JSON output — designed for autonomous systems.

export USERTOLD_API_KEY=$(your_api_key)

usertold auth whoami --json

usertold init \
  --name "My Product" \
  --study-title "User Research Study" \
  --format json \
  --yes

# Then add your OpenAI key for the project (encrypted at rest, scoped to this project):
usertold project use <orgHandle>/<projectHandle>
usertold config set --key openai_api_key --value sk-...

This creates a project, study, intake, and generates a snippet in a single non-interactive command.

MCP Integration

For Claude, Cursor, and other agents with MCP support:

Use a single MCP JSON-RPC endpoint with project-aware tool calls and resource reads:

  • POST /mcp
  • Auth: connect via OAuth (Authorization Code + PKCE). Do not manually provision bearer headers in normal Claude/Cursor setup.
  • Discovery: /.well-known/openid-configuration and /.well-known/oauth-protected-resource
  • Dynamic client registration: supported at POST /api/oauth/register; pre-registered integrations can still use static clients.

Examples:

  • initialize to discover available tools/prompts/resources and result.user.personal_org_handle
  • resources/read on usertold://me for the authenticated user profile and workspace handle
  • tools/list and tools/call for actions like work.create_from_evidence or studies.validate_script
  • resources/list and resources/read for project-scoped context (project://... URIs)

MCP is optional—if you already use the dashboard or REST API, continue using those. MCP is meant to complement those flows for teams that want tighter autonomous loops.

See the API Reference for full endpoint documentation.

Next Steps