Skip to content
Synthetic Users

Multi-persona runs

A run can carry 1 to N personas. Each persona executes in its own SessionDO + Container in parallel. When the last session completes, we synthesize a cross-persona aggregate report.

When to fan out

  • You’re choosing between two onboarding flows and want both audience reads.
  • You’re shipping a B2B feature where buyer and end-user disagree.
  • You want a “do these confusion points cluster?” answer that one persona can’t give.

Submitting a fan-out

Terminal window
curl -s -X POST "$API_URL/runs" \
  -H "Authorization: Bearer $SYNTHUSERS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "target_url": "https://staging.example.com/",
    "persona_ids": ["pers_smb_owner", "pers_anxious", "pers_power_user"],
    "task": "Sign up and create your first project.",
    "duration_budget": "short"
  }'

The hard cap is 10 personas per run.

const res = await fetch(`${API_URL}/runs`, {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.SYNTHUSERS_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    target_url: "https://staging.example.com/",
    persona_ids: ["pers_smb_owner", "pers_anxious", "pers_power_user"],
    task: "Sign up and create your first project.",
  }),
});
const { run_id } = await res.json();

What you get back

runs/<run_id>/
├── sessions/<sid_1>/
│   ├── report.json
│   ├── report.md
│   ├── report.html
│   └── screenshots/
├── sessions/<sid_2>/...
├── sessions/<sid_3>/...
└── aggregate-report.json
    aggregate-report.md
    aggregate-report.html

The aggregate report includes:

  • Cross-persona confusion clusters — when 2+ personas hit the same wall.
  • Per-persona quotes attributed to each voice.
  • Would-sign-up roll-up — how many personas got far enough to convert.

Fetching the aggregate

Terminal window
curl -s "$API_URL/runs/$RUN_ID/aggregate-report.json" \
  -H "Authorization: Bearer $SYNTHUSERS_API_KEY"

The aggregate is also available as .md and .html. Each persona’s own report stays at runs/:id/sessions/:sid/report.*. Check the run’s aggregate_status field — the aggregate is ready when it reads ready.

Cost

You’re billed per completed session, not per run. A 3-persona run bills three sessions. Cancelled / errored sessions don’t bill.