Quickstart

Three 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

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. Configure your OpenAI API key

UserTold.ai runs interviews and extracts evidence using OpenAI inference. Add your OpenAI API key in Project Settings before activating a study.

  • Inference costs are billed directly to your OpenAI account (BYOK)
  • Keys are encrypted at rest, scoped per project, and never logged
  • You can remove or rotate the key any time from Project Settings

See our Security page for details on 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 intake handle is on the intake detail page — it's the human-readable slug used in URLs and embed code.

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 project-aware verification.

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.

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