Skip to content
Synthetic Users

Quickstart

This walkthrough takes you from zero to a completed run with a report file in under five minutes.

1. Sign up

Visit app.syntheticusers.io and create an account. Synthetic Users is in early access, which is currently free — see the Billing page in the dashboard for your account’s current status.

2. Mint an API key

In the dashboard, open API Keys → New key. Give it a name (e.g. local-dev). The plaintext is shown once — copy it into your secret manager immediately. Subsequent visits only show the prefix.

Terminal window
export SYNTHUSERS_API_KEY="sk_live_..."
export API_URL="https://api.syntheticusers.io"

3. Pick a persona

Your account comes with a library of ready-made personas — a neutral Default for baseline reviews, plus audience-specific voices. List them and pick one whose voice matches your target audience.

Terminal window
curl -s "$API_URL/personas" \
  -H "Authorization: Bearer $SYNTHUSERS_API_KEY" \
  | jq '.items[] | { id, name, source }'

Note one id — you’ll pass it into the run.

4. Fire a run

Terminal window
curl -s -X POST "$API_URL/runs" \
  -H "Authorization: Bearer $SYNTHUSERS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "target_url": "https://your-staging.example.com",
    "persona_ids": ["pers_..."],
    "task": "Try to sign up for the product and create your first project.",
    "duration_budget": "short"
  }'
# → { "run_id": "run_01H...", "status": "queued" }

The API returns immediately with a run_id. The agent runs asynchronously.

5. Poll for completion

Terminal window
curl -s "$API_URL/runs/<run_id>" \
  -H "Authorization: Bearer $SYNTHUSERS_API_KEY"
# → { "status": "completed", "sessions": [...] }

A short run usually completes within a couple of minutes.

6. Read the report

Terminal window
# Per-session report (JSON)
curl -s "$API_URL/runs/<run_id>/sessions/<sid>/report.json" \
  -H "Authorization: Bearer $SYNTHUSERS_API_KEY"


# Or the Markdown
curl -s "$API_URL/runs/<run_id>/sessions/<sid>/report.md" \
  -H "Authorization: Bearer $SYNTHUSERS_API_KEY"

The hosted report viewer lives at https://app.syntheticusers.io/r/<run_id> (sign-in required).

Next