lewn

Poll a calibrated panel of synthetic respondents from your code. Ask any question, get back how a population actually splits — with an honest confidence read and panel composition.

npm install getlewn

Quick start

import { Lewn } from "getlewn";

const lewn = new Lewn({ apiKey: process.env.LEWN_API_KEY! });

const res = await lewn.poll({
  question: "Would you pay $15/mo for an AI calendar assistant?",
  options: ["Yes", "No", "Maybe"],
  audience: { market: "national_us", n: 300 },
});

console.log(res.summary);
// "Among US adults (n=300), Yes leads at 38% (vs No 34%, Maybe 28%). Directional read."
console.log(res.distribution);
// [ { option: "Yes", pct: 38.2, count: 115 }, ... ]
console.log(res.confidence);       // { score: 0.62, label: "Directional", tier: "amber" }
console.log(res.panel_composition); // { n_real: 150, n_synthetic: 150, n_total: 300, ... }

res.summary is a ready-to-print sentence — great for logging or handing straight to a coding agent. Everything else (res.distribution, res.confidence, res.panel_composition) is the structured detail.

Get an API key at https://lewn.ai/developers (Pro and Research plans).

Calibrated vs. free-form

• Pass 2–6 options → a calibrated multiple-choice read (the trustworthy path; benchmarked against Pew/Gallup).
• Omit options → an uncalibrated free-form read (directional only, no numeric accuracy claim).

Always check res.confidence.tier before leaning on a number.

API

new Lewn({ apiKey, baseUrl?, timeout? })

• apiKey — your sk-lew-... key (required).
• baseUrl — defaults to https://lewn.ai/api/v1.
• timeout — ms, default 60000.

lewn.poll(params) → Promise<PollResult>

• question: string (required)
• options?: string[] — 2–6 for calibrated MC
• audience?: { market?: string; n?: number } — e.g. market: "national_us" | "atlanta" | "texas"; n is clamped to your plan's per-query max
• requestId?: string — idempotency key (a retried request bills once)

Errors throw LewnError with .status and .code (UNAUTHORIZED, FORBIDDEN, RATE_LIMITED, TIMEOUT, API_ERROR, …).

Billing

Metered by respondents queried against your plan's monthly pool. res.usage shows respondents_billed, month_used, and month_limit. Per-query size and rate scale with your plan (Pro $70 / Research $200).

Made by lewn · synthetic respondents are estimates, not guarantees.