Research API
A calibrated panel, in one HTTP call.
Ask any question in code and get back how a representative panel of people would answer — a structured distribution with an honest confidence read and panel composition. No survey to build, no panel to recruit, no waiting. Benchmarked against 460 ground-truth questions from Pew, Gallup & UT/TPP (~7.5 pp MAE on structured items).
npm install lewsearch · POST /api/v1/cohort/query · Bearer sk-lew-…
What you get
One endpoint
POST a question, options, and an audience. Get a calibrated answer distribution back as JSON.
Honest output
Every response includes panel composition, a confidence tier, and a one-line summary you can read at a glance.
Targetable & metered
Set the market and panel size; usage is metered by respondents queried against your plan's monthly pool.
Quick start
Running in under a minute.
Works in any language over plain HTTP — or use the typed JavaScript/TypeScript SDK.
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
Install the SDK:
npm install lewsearch
import { Lewsearch } from "lewsearch";
const ls = new Lewsearch({ apiKey: process.env.LEWSEARCH_API_KEY });
const res = await ls.poll({
question: "Would you switch brands at $4.99?",
options: ["Definitely", "Probably", "Probably not", "No"],
audience: { market: "national_us", n: 500 },
});
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
Not focus-group software. A research operating system.
Price sensitivity at scale
Loop the same concept across price points and read the demand curve from thousands of calibrated respondents — conjoint-style insight in minutes, not a $50k–$100k study.
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.
Example: a price demand curve
// Trace a demand curve across price points — minutes, not weeks.
const prices = [2.99, 3.99, 4.99, 5.99];
for (const price of prices) {
const res = await ls.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 + "% would buy");
}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 · optional | Market id, e.g. national_us, columbus, atlanta, texas. Defaults to national_us. |
| 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. |
Response
{
"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"
},
"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.
Keys & scale
The API ships with Enterprise.
Per-seat API keys
Programmatic access is part of an Enterprise deployment. We provision per-seat keys with an audit log, and limits are sized to your contract — talk to sales to get set up.
Book a demo →Enterprise · dedicated inference
On a dedicated Lewis instance there are no external API calls and no per-call inference cost — so your team can query and re-query at the scale your research needs, with per-seat keys and an audit log. Limits are sized to your deployment.
See Enterprise →