Research API
A calibrated panel, in one HTTP call.
Ask any question in code and get back how a panel of simulated respondents would split: a structured distribution with an honest confidence read and panel composition. No survey to build, no panel to recruit. On the calibrated 50-state benchmark, the average miss is 7.07 points on the best 80% of 1,521 scored questions, and 10.02 points across all of them.
POST /api/v1/cohort/query · Bearer sk-lew-… · for client teams
What you get
One endpoint
POST a question, options, and an audience. Get a calibrated answer distribution back as JSON.
Structured output
Every response includes panel composition, a confidence tier, and a one-line summary.
Targetable
Set the market and panel size. Volume is scoped with the client team.
Quick start
One HTTP call.
One endpoint over plain HTTP, so it works from any language with no client library.
curl
curl https://lewsearch.com/api/v1/cohort/query \
-H "Authorization: Bearer sk-lew-..." \
-H "Content-Type: application/json" \
-d '{
"question": "Would you switch brands at $4.99?",
"options": ["Definitely", "Probably", "Probably not", "No"],
"audience": { "market": "national_us", "n": 500 }
}'TypeScript / JavaScript
The supported client is fetch against the REST API. MCP access is part of every Enterprise deployment and is configured per workspace.
const res = await fetch("https://lewsearch.com/api/v1/cohort/query", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.LEWSEARCH_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
question: "Would you switch brands at $4.99?",
options: ["Definitely", "Probably", "Probably not", "No"],
audience: { market: "national_us", n: 500 },
}),
}).then((r) => r.json());
console.log(res.summary);
// "Among US adults (n=500), Probably leads at 38% (vs No 27%...). Directional read."
console.log(res.distribution, res.confidence);Programmatic research
Wire the panel into your own tools.
Stated-preference price screens
Loop the same concept across price points and read stated preference. That is a concept screen, not a validated demand curve, conjoint, or checkout experiment.
Message testing across segments
Fire the same claim at dozens of audience definitions in parallel and compare how each segment splits. Find the angle that lands before you spend on media.
Concept & feature screening
Rank features, names, or positioning across a representative panel programmatically. Wire it straight into your prioritization pipeline.
Always-on research ops
Embed calibrated reads into dashboards, agents, and internal tools. Every response ships an honest confidence tier and panel composition, so automation stays defensible.
Illustrative example: a stated-preference price screen
// Illustrative concept screen across stated-preference prices. Not a
// validated demand curve, conjoint, or conversion forecast.
const prices = [2.99, 3.99, 4.99, 5.99];
for (const price of prices) {
const res = await poll({
question: "Would you buy this at $" + price + "?",
options: ["Yes", "No"],
audience: { market: "national_us", n: 1000 },
});
const yes = res.distribution.find((d) => d.option === "Yes")?.pct ?? 0;
console.log("$" + price + " -> " + yes + "% stated yes");
}
// poll() is your own four-line wrapper around the fetch above.Endpoint reference
POST /api/v1/cohort/query
Authenticate with Authorization: Bearer sk-lew-…. Body is JSON.
Request body
| Field | Type | Description |
|---|---|---|
| question | string · required | The question to put to the panel. |
| options | string[] · optional | 2-6 options for a calibrated multiple-choice read. Omit for a directional free-form read (no numeric accuracy claim). |
| audience.market | string · required | Market id, e.g. national_us, columbus, atlanta, texas. Unknown or missing ids are rejected. |
| audience.n | number · optional | Panel size. Clamped to your plan's per-query maximum. |
| request_id | string · optional | Idempotency key. A retried request with the same id is billed once. |
Illustrative response
Example only. Counts and percentages are invented for the shape of the payload.
{
"ok": true,
"request_id": "b1f2...",
"mode": "mc",
"question": "Would you switch brands at $4.99?",
"summary": "Among US adults (n=500), Probably leads at 38% ...",
"distribution": [
{ "option": "Probably", "pct": 38.0, "count": 190 },
{ "option": "No", "pct": 27.0, "count": 135 }
],
"panel_composition": {
"n_real": 500, "n_synthetic": 0, "n_total": 500,
"market_mode": "live_panel", "market": "national_us",
"respondent_origin": "synthetic_panel"
},
"confidence": { "score": 0.74, "label": "Directional", "tier": "amber" },
"usage": { "respondents_billed": 500, "month_used": 12500, "month_limit": 1000000 }
}Always check confidence.tier before leaning on a number. Pass 2-6 options for the calibrated multiple-choice path; omit them for a directional free-form read. Every respondent is simulated. n_real counts persistent census-grounded panel records. n_synthetic counts on-the-fly generated agents when the pool is short. Neither field is a human complete. respondent_origin is always synthetic_panel.
Keys & scale
API access is for client teams.
REST API
Client teams get the research API: multiple active keys, panels sized to the engagement, and respondent-level results. Accounts are set up by the Lewsearch team. Email us and we will send the first key.
Book a demo →Enterprise deployments
An Enterprise deployment runs on a dedicated Lewis instance, with no external model API calls. MCP access is part of every Enterprise deployment and is configured per workspace. Rate limits and the respondent pool are sized to the engagement.
See Enterprise →Get started
The API is set up for client teams.
REST API for client teams. MCP access is configured per Enterprise workspace.