Synthetic Users (syntheticusers.com) platform help — run AI-moderated research studies (problem-exploration and concept-testing interviews) against synthetic participants instead of recruiting real people, grounded in your own data via RAG, with insights reports, saturation scoring, and a full REST API (Bearer auth, Python + TypeScript SDKs, SSE streaming, PDF export). Use when setting up a Synthetic Users study or audience, interpreting a synthetic interview report, grounding participants in your own customer data, pulling study transcripts or summaries via the API, wiring the create-study to interview to summary flow into a pipeline, or judging whether a synthetic 'yes' is real demand. Do NOT use for comparing idea-validation or persona tools across the market (use /sales-idea-validation) or analyzing real-customer NPS/VoC feedback (use /sales-customer-feedback).
Synthetic Users (syntheticusers.com) platform help — run AI-moderated research studies (problem-exploration and concept-testing interviews) against synthetic participants instead of recruiting real people, grounded in your own data via RAG, with insights reports, saturation scoring, and a full REST API (Bearer auth, Python + TypeScript SDKs, SSE streaming, PDF export). Use when setting up a Synthetic Users study or audience, interpreting a synthetic interview report, grounding participants in your own customer data, pulling study transcripts or summaries via the API, wiring the create-study to interview to summary flow into a pipeline, or judging whether a synthetic 'yes' is real demand. Do NOT use for comparing idea-validation or persona tools across the market (use /sales-idea-validation) or analyzing real-customer NPS/VoC feedback (use /sales-customer-feedback).
argument-hint
[describe what you need help with in Synthetic Users]
license
MIT
version
1.0.0
tags
["sales","pre-launch","platform"]
github
https://github.com/SyntheticUsers
Synthetic Users Platform Help
Synthetic Users (syntheticusers.com) is an AI synthetic user-research platform: you define an
audience, write a topic guide, and run interviews against AI synthetic participants —
multi-agent personas with stable OCEAN personality profiles — instead of recruiting real respondents.
Three interview types: problem exploration, concept testing, and custom script. You can
ground studies in your own data via RAG (customer interviews, support tickets, segment
definitions), and it returns an insights report (themes, executive summary, verbatim quotes) with
saturation scoring to tell you when you've heard enough. Unusually for this cluster it ships a
full REST API (Bearer auth, Python + TypeScript SDKs, SSE streaming, PDF export).
Its signal is directional, not demand: synthetic participants model existing/public/training data,
so they skew agreeable, generic, and Western-biased and cannot surface a genuinely new unmet
need. Treat any synthetic result as a hypothesis to disconfirm with real behavior, not a green
light.
Step 1 — Gather context
If references/learnings.md exists, read it first for accumulated platform knowledge.
Ask only what you can't infer:
What do you want from Synthetic Users?
A) Set up a study — pick an interview type (problem exploration / concept testing / custom script)
B) Define or generate an audience of synthetic participants
C) Ground a study in your own data (RAG upload) for more specific answers
D) Interpret an insights report / transcripts / saturation score you already ran
E) Automate it — pull studies/summaries/transcripts via the API, or wire the flow into a pipeline
F) Decide whether to trust it — is this a valid stand-in for real research?
What's the research question and who's the audience? A sharp audience + topic guide yields a
usable result; a vague one yields generic filler.
Skip-ahead: if the user wants to compare synthetic-research/persona/idea tools across the market, or
the validate-before-building method, that's a /sales-idea-validation question — route in Step 2.
Step 2 — Route or answer directly
If the user's question is about…
Route to
Comparing synthetic-research/persona/idea tools, or the validate-before-building method
/sales-idea-validation {question}
Running a real demand test (smoke-test page, waitlist, pre-sale) after synthetic signal
A data-grounded persona you chat with (from your CRM/GA4), not a full study
/sales-delve or /sales-marketing-mary{question}
When routing, give the exact command: "This is a {domain} question — run: /sales-idea-validation {original question}"
Otherwise, answer Synthetic Users-specific questions using Step 3.
Step 3 — Synthetic Users platform reference
Read references/platform-guide.md for the full reference — the three interview types, audience &
RAG grounding, the study → interview → summary → knowledge-graph → PDF workflow, the API/webhook/UI-only
tag on each module, best-effort usage-based pricing and trial, the integration/automation surface, the
data model (Study/Audience/SyntheticUser/Conversation JSON shapes), and quick-start recipes.
For raw endpoints, auth, and JSON schemas, read references/syntheticusers-api-reference.md.
Answer using only the relevant section — don't dump the full reference.
Step 4 — Actionable guidance
A synthetic "yes" is not demand — say so every time. Whatever the user asks, make explicit that
synthetic participants model existing/public/training data, so they run agreeable, generic, and
Western-biased and can be confidently wrong. Frame every result as a hypothesis to disconfirm
with a real behavior test (smoke-test click, reply, pre-sale) — keep the objections, angles, and
language it surfaces (its real value), take the go/no-go from real strangers, and route the real test
to /sales-idea-validation.
Use it for what it's genuinely good at. Fast, cheap pre-testing of messaging/concepts/objections
and directional pre-launch signal, filling a persona hypothesis, or coverage when a real panel is
slow — not discovering a new unmet need and not a standalone validity verdict (surveys of
researchers put standalone trust in the low single digits).
Ground it in your own data (RAG) and sharpen the audience — output tracks input. A vague audience or
topic guide yields generic filler ("garbage in, garbage out"). Tell the user to upload real data
(interviews, tickets, segment defs) and write a specific audience + topic guide; note grounding is a
paid/RAG add-on to the interview cost.
Read saturation, don't chase volume. ~10–12 participants typically reach saturation (no new
themes); more interviews mostly repeat. Point to the saturation score, not raw interview count, and
treat the verbatim quotes as leads to test, not facts.
Present pricing as best-effort and point to the live page. It's usage-based (~$2–60 per
interview, +RAG), with a 7-day trial and API/deeper integration on higher tiers — say figures are
best-effort and confirm at syntheticusers.com/pricing before relying on them.
For automation, use the real API. Auth is Authorization: Bearer <API_KEY>, base URL
https://api.syntheticusers.com/api/v1; pagination is page + size (size max 100). The core
flow is POST /studies → POST /studies/{id}/interview → POST /studies/{id}/summary →
GET /studies/{id}/pdf; there are no webhooks — poll study status or subscribe to
GET /projects/{id}/stream (SSE). Give a concrete cURL/Python snippet from
references/platform-guide.md.
If you discover a gotcha or tip not in references/learnings.md, append it there with today's date.
Gotchas
Best-effort from research (2026-07) — usage-based pricing, trial terms, RAG costs, and API surface move;
verify at syntheticusers.com and docs.syntheticusers.com.
Sycophancy / agreeableness bias. Synthetic participants tend to please — they give shallow,
overly favorable feedback and can approve a concept real users would reject. Never read a positive
synthetic reaction as validation.
It can't surface a NEW unmet need. It models existing/public data, so it's strongest at
pre-testing a hypothesis you already have and weakest at discovery. Don't use it to "find the problem."
Western/geographic and identity bias. Outputs skew toward Western, majority perspectives and can
flatten identity groups — be cautious generalizing across markets/segments.
Garbage in, garbage out. A thin audience definition or no RAG data yields generic filler. Ground
the study and write a specific topic guide before trusting any theme.
No webhooks. The API has no webhook callbacks — long-running studies are tracked by polling
status or the SSE /projects/{id}/stream endpoint, not push notifications.
PDF/report is a heavy endpoint.GET /studies/{id}/pdf generates on demand (can 500 on error) and
returns binary — handle non-200s and stream to file.
Related skills
/sales-idea-validation — The tool-agnostic validate-before-building method + the full synthetic-research/persona/validator tool landscape (use this to actually decide build-or-not; a synthetic "yes" is not demand)
/sales-imario — iMario platform help (the closest peer — a synthetic-research canvas whose unit is a reusable Synthetic Individual with cross-session memory, run across six jobs [research, concept validation, sales rehearsal, content testing, journey design, AI-agent personality]; trades Synthetic Users' documented public REST API for reusable-persona breadth — its API is Pro-gated and undocumented)
/sales-ditto — Ditto platform help (the other synthetic-research tool with a real public REST API — recruits census-calibrated demographic panels [country/state/age] and ships a free-tier key + official Claude Code skills; Synthetic Users' edge is documented Python/TS SDKs + SSE streaming + RAG grounding, Ditto's is demographic calibration + a free API on-ramp)
/sales-delve — Delve AI platform help (data-grounded personas + Digital Twins + Synthetic Research built from your real GA4/CRM/social data — the persona-you-chat-with counterpart; has a paid, gated API)
/sales-marketing-mary — Marketing Mary platform help (interactive buyer personas you converse with, grounded in real CRM/GA4 data; UI-only, no public API)
/sales-customer-feedback — Real-customer NPS/CSAT/VoC strategy across tools (use once you have live customers; synthetic research is pre-launch only)
/sales-funnel — Build the smoke-test / fake-door landing page that turns a synthetic hypothesis into a real demand test
/sales-do — Not sure which skill to use? The router matches any sales objective to the right skill. Install: npx skills add sales-skills/sales --skill sales-do -a claude-code
Examples
Example 1: "The synthetic interviews loved my idea — should I build it?"
User says: "I ran a concept test on Synthetic Users and 9 of 10 synthetic participants said they'd use it. Green light?"
Skill does: Explains synthetic participants model existing/training data and skew agreeable, so a
near-unanimous "yes" is a directional signal, not demand — it can approve a concept real strangers
ignore. Tells the user to mine the transcripts for objections and language (the real value) and take
the go/no-go from a real behavior test — a smoke-test click or pre-sale — routed via
/sales-idea-validation. Notes ~10 participants likely hit saturation, so more interviews won't add
signal.
Result: The founder keeps the angles, runs a real fake-door test before writing code.
Example 2: Grounding a study in real data for a specific audience (references/platform-guide.md)
User says: "How do I make Synthetic Users give answers specific to my B2B ops buyers, not generic fluff?"
Skill does: Says output tracks input — define a sharp audience (role, context, psychographics)
and upload real data via RAG (past interviews, support tickets, segment defs) so participants are
grounded, noting RAG is a paid add-on on top of the per-interview cost. Explains the problem
-exploration vs concept-testing vs custom-script choice and to write a focused topic guide. Frames each
theme as a hypothesis to confirm with real users.
Result: A grounded study with specific, testable themes instead of generic filler.
Example 3: Pulling study summaries into a data pipeline via the API (developer/automation)
User says: "I want to run a study and push the summary + transcripts into our warehouse automatically. What's the API?"
Skill does: Gives the flow — auth Authorization: Bearer <API_KEY>, base
https://api.syntheticusers.com/api/v1; POST /studies → POST /studies/{id}/interview →
POST /studies/{id}/summary → GET /studies/{id} (read status/transcripts) → GET /studies/{id}/pdf.
Notes no webhooks — poll status or subscribe to GET /projects/{id}/stream (SSE) — and pagination
is page + size (max 100). Points to the Python/TypeScript SDKs and a cURL/Python snippet in
references/platform-guide.md.
Result: The user wires the create → interview → summarize → export flow with polling, no webhook dependency.
Troubleshooting
"The synthetic participants agreed with everything — is that real?"
Symptom: Interviews return uniformly positive, agreeable feedback that feels too good.
Cause: LLM-based participants exhibit sycophancy — they model plausible agreement and skew favorable.
Solution: Discard the "verdict," keep the objections and language surfaced, and validate the
concept with real behavior (smoke test, pre-sale). Ground the study in real data and sharpen the
audience to reduce generic agreement. Cross-check via /sales-idea-validation.
Results feel generic / could describe anyone
Symptom: Themes are vague and not specific to your product or buyer.
Cause: Thin audience definition and no RAG grounding — "garbage in, garbage out."
Solution: Write a specific audience + topic guide and upload your own data (interviews,
tickets, segment defs) via RAG so participants are grounded; note RAG adds cost. Re-run with a focused
concept.
"My long study never 'finishes' — how do I know when it's done via the API?"
Symptom: After POST /studies/{id}/interview, the study stays processing and there's no callback.
Cause: The API has no webhooks; long-running studies complete asynchronously.
Solution: PollGET /studies/{id} and read status, or subscribe to the SSE stream at
GET /projects/{id}/stream for model events. Use page/size pagination on list endpoints. See
references/syntheticusers-api-reference.md.
