Survey Response SDK
What would a panel of your customers say?
You need to know whether shoppers would move to a new own-brand line, and fielding a real panel is three weeks and a budget line. Put the questionnaire to 150 simulated customers drawn from real purchase histories, read the spread of answers today, and field the real panel on the questions that still look uncertain.
The panel lands 64% of its answers where 1,013 real respondents landed theirs, against 52% for a frontier AI. The study is on the research pages.
FeatureNotEnabledError with exactly that message. Ask your EGGai
contact to enable it.Quick start
from eggai import SurveySimulator survey = SurveySimulator(api_key) result = survey.ask( "Would you switch to our own-brand line?", ["Definitely", "Maybe", "No"], # or customers = {id: profile} for your own list panel = "shoppers aged 18-55 who buy fresh " "produce most weeks", n = 150, guidelines = "let the unsure stay unsure", ) result.distribution # {"Definitely": 0.21, "Maybe": 0.44, "No": 0.35} result.transcripts # the reasoning behind each answer result.crosstab("segment") # the same spread, split by trait
import { SurveySimulator } from '@eggai-sdk/core'; const survey = new SurveySimulator(apiKey); const result = await survey.ask( 'Would you switch to our own-brand line?', { options: ['Definitely', 'Maybe', 'No'], // or customers: {id: profile} for your own list panel: 'shoppers aged 18-55 who buy fresh produce most weeks', n: 150, guidelines: 'let the unsure stay unsure', }, ); result.distribution; // { Definitely: 0.21, Maybe: 0.44, No: 0.35 } result.transcripts; // the reasoning behind each answer result.crosstab('segment'); // the same spread, split by trait
Leave options off for an open-ended question. Describe a panel and it is drawn for
you from real purchase histories — or pass customers to put the questionnaire to your
own respondents.
Why there is only one model here
This is the run with no proposer. You supply the questions, so there is nothing to optimise — only a panel to answer them. Each respondent is a separate twin drawn from a real purchase history, answering independently. The result is a spread rather than one confident answer repeated — which is the whole difference between a simulated panel and a single model asked the same question 150 times.
The reward the twin was trained against was distribution-matching, never a single confident answer. A panel that agrees with itself more than real people do is precisely the failure this is built to avoid.
The result object
| Field | Meaning |
|---|---|
distribution | Share of the panel per option, in your option order. |
transcripts | One entry per respondent: the answer and the first-person reasoning behind it. |
crosstab(trait) | The same spread, split by a respondent trait —
"segment", "age", or any extra column you brought. |
n | Respondents answered. |
rows | The raw per-respondent rows. |
Reading a spread honestly
- Wide spread = real uncertainty. That is signal, not noise — those are the questions to put to a real panel.
- 150 respondents is a default, not a limit — but past a few hundred you are resampling the same behaviour space, not learning more.
- Field the real thing on what stays uncertain. The product is a cheap first pass that tells you where the expensive pass is worth it.