# Synthetic Audience Simulator — AI Survey on Real Census Data (`noniner/synthetic-audience-simulator`) Actor

Survey a synthetic audience grounded in real Census and World Bank microdata. Give it a question and target demographic; get back a weighted response distribution with segment breakdowns.

- **URL**: https://apify.com/noniner/synthetic-audience-simulator.md
- **Developed by:** [Fredrik Hansson](https://apify.com/noniner) (community)
- **Categories:** AI, Marketing, Business
- **Features:** Limited permissions
- **Stats:** 1 total users, 0 monthly users, 96.8% runs succeeded, 0 bookmarks
- **User rating**: 5.00 out of 5 stars

## Pricing

from $220.00 / 1,000 100 synthetic respondents

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Synthetic Audience Simulator

Ask any question to a **representative synthetic audience** and get a simulated response distribution — without fielding a real survey. Every respondent is a digital person drawn from **real public microdata**, and every result ships with an honest **calibration score** that tells you how far to trust it.

Use it to pre-test messaging, concepts, pricing, naming and opinion in minutes, as a fast first read before (not instead of) a real study.

### How it works

1. **Real grounding.** The audience is sampled from real, public, commercially-usable population data:
   - **US** (with a free `CENSUS_API_KEY`): deep **Census ACS PUMS microdata** — real joint structure across age, sex, education and income.
   - **Any country / global**: **World Bank** age-by-sex population structure (keyless). Age and sex are real and representative; other traits are inferred by the model from the country context.
2. **Representative sampling.** Personas are drawn proportional to population weight, then filtered to your audience (age, sex, free-text targeting).
3. **Simulation.** A language model is conditioned on each individual persona and answers your question in character.
4. **Weighted aggregation.** Answers are aggregated into a distribution with segment breakdowns and a margin of error.
5. **Calibration (optional).** Back-test the engine against a real benchmark dataset to get an honest, per-question accuracy number.

### Input

| Field | Description |
|-------|-------------|
| `question` | The question, exactly as a respondent would read it. **Required.** |
| `questionType` | `single_choice`, `scale_1_5`, or `open_text`. |
| `options` | Answer options for `single_choice`. |
| `market` | ISO country code (`US`, `GB`, `SE`, `DE`, …) or `global`. |
| `audienceDescription` | Plain-language targeting, e.g. "regular coffee drinkers". |
| `ageMin` / `ageMax` / `sex` | Demographic filters. Defaults to adults 18+. |
| `sampleSize` | Number of synthetic respondents (20–2000). |
| `breakdownBy` | Report segments: `age_group`, `sex`, `education`, `income_bracket`, `region`. |
| `mode` | `simulate` (run a study) or `calibrate` (back-test accuracy). |
| `benchmarkDatasetId` | For `calibrate`: a dataset of `{ profile, answer }` real records. |

### Output

- **REPORT** (key-value store): weighted response distribution, topline with margin of error, segment breakdowns, confidence level, methodology and disclaimer.
- **Dataset**: one row per simulated respondent — profile, answer, rationale and weight.
- In `calibrate` mode, REPORT contains real-vs-simulated shares, mean absolute error and total variation distance.

### Calibration — the honest part

Synthetic respondents are a powerful shortcut, but they are a model, not a mirror of reality. `calibrate` mode lets you measure the gap on your own topic: supply a real labelled dataset (`{ profile, answer }`) and the engine simulates each real profile, then reports how closely the predicted distribution matches the real one. Aggregate predictions are typically far more reliable than any single individual answer — the report makes both explicit.

### Limitations

- Simulated responses are **directional**. Validate before high-stakes decisions.
- Non-US markets are grounded on age/sex structure only; other traits are model-inferred.
- Like any model, it can under-represent minority and extreme views. Calibrate for topics that matter.

### Configuration

- `OPENAI_API_KEY` — required.
- `CENSUS_API_KEY` — optional; enables deep US microdata grounding.
- `CENSUS_STATES`, `CENSUS_YEAR` — optional overrides for the US state basket and ACS year.

### Local development

```bash
npm install
OPENAI_API_KEY=sk-... npm run start:dev
```

Edit `storage/key_value_stores/default/INPUT.json` to set the input.

# Actor input Schema

## `question` (type: `string`):

The question to ask your synthetic audience, exactly as a respondent would read it.

## `questionType` (type: `string`):

single_choice: pick one of your options. scale_1_5: a 1–5 agreement/likelihood scale. open_text: a free-text answer (summarised into themes).

## `options` (type: `array`):

Answer options for single_choice questions. One per line. Ignored for scale / open_text.

## `market` (type: `string`):

ISO country code the audience should represent, e.g. US, GB, SE, DE. US is grounded in deep Census microdata (age, sex, education, income, region); other markets are grounded in real age/sex population structure (World Bank) with the model supplying local context. Use 'global' for a world-population blend.

## `audienceDescription` (type: `string`):

Narrow the audience in plain language, e.g. 'regular coffee drinkers', 'small-business owners', 'parents of young children'. The sampled population is filtered/weighted toward this description before simulation.

## `ageMin` (type: `integer`):

Only include respondents at or above this age.

## `ageMax` (type: `integer`):

Only include respondents at or below this age.

## `sex` (type: `string`):

Restrict the audience by sex, or leave as 'any'.

## `sampleSize` (type: `integer`):

How many digital respondents to simulate. More respondents = tighter estimates but higher cost. Charged per 100 respondents.

## `breakdownBy` (type: `array`):

Report the results broken down by these dimensions. Allowed values: age_group, sex, education, income_bracket, region. One per line.

## `mode` (type: `string`):

simulate: run a study against the synthetic audience. calibrate: back-test the engine against a real benchmark dataset (supplied via benchmarkDatasetId) and report honest accuracy.

## `benchmarkDatasetId` (type: `string`):

Apify dataset ID with real labelled records for calibrate mode. Each item: { profile: {...}, answer: "<real answer>" }. The engine simulates each profile and compares against the real answer.

## `maxConcurrency` (type: `integer`):

How many respondents to simulate in parallel.

## `model` (type: `string`):

Override the model (default gpt-4o-mini).

## Actor input object example

```json
{
  "question": "How likely would you be to try a new oat-milk energy drink sold in a 250ml can?",
  "questionType": "single_choice",
  "options": [
    "Very likely",
    "Somewhat likely",
    "Not sure",
    "Somewhat unlikely",
    "Very unlikely"
  ],
  "market": "US",
  "sex": "any",
  "sampleSize": 300,
  "breakdownBy": [
    "age_group",
    "sex"
  ],
  "mode": "simulate",
  "maxConcurrency": 8
}
```

# Actor output Schema

## `report` (type: `string`):

The aggregated result: weighted response distribution, segment breakdowns, confidence and methodology.

## `respondents` (type: `string`):

One row per simulated respondent — profile, answer and sampling weight.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "question": "How likely would you be to try a new oat-milk energy drink sold in a 250ml can?",
    "options": [
        "Very likely",
        "Somewhat likely",
        "Not sure",
        "Somewhat unlikely",
        "Very unlikely"
    ],
    "breakdownBy": [
        "age_group",
        "sex"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("noniner/synthetic-audience-simulator").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "question": "How likely would you be to try a new oat-milk energy drink sold in a 250ml can?",
    "options": [
        "Very likely",
        "Somewhat likely",
        "Not sure",
        "Somewhat unlikely",
        "Very unlikely",
    ],
    "breakdownBy": [
        "age_group",
        "sex",
    ],
}

# Run the Actor and wait for it to finish
run = client.actor("noniner/synthetic-audience-simulator").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "question": "How likely would you be to try a new oat-milk energy drink sold in a 250ml can?",
  "options": [
    "Very likely",
    "Somewhat likely",
    "Not sure",
    "Somewhat unlikely",
    "Very unlikely"
  ],
  "breakdownBy": [
    "age_group",
    "sex"
  ]
}' |
apify call noniner/synthetic-audience-simulator --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,noniner/synthetic-audience-simulator"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/Lvb9BL2z8mEvLuTz2/builds/yOLnOLwcpGqi5NjaW/openapi.json
