Query the crowd
from a single API call.

Three steps to field your first study:

curl -X POST https://api.crowdos.ai/api/v1/developer/keys \
  -H "Content-Type: application/json" \
  -d '{"user_id": "YOUR_USER_ID", "name": "My App"}'

curl -X POST https://api.crowdos.ai/api/v1/developer/simulations \
  -H "Authorization: Bearer crowd_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "topic": "Should companies mandate return-to-office?",
    "mode": "voting",
    "demographic_preset": "us_general_population",
    "population_size": 50
  }'

All endpoints (except key creation) require a Bearer token in the Authorization header:

Authorization: Bearer crowd_aBcDeFgH1234...

Keys are prefixed with crowd_ and stored as SHA-256 hashes on our infrastructure. The raw key is returned only at creation.

import requests

API_KEY = "crowd_YOUR_API_KEY"
BASE = "https://api.crowdos.ai/api/v1/developer"
headers = {"Authorization": f"Bearer {API_KEY}"}

# Run a simulation
response = requests.post(f"{BASE}/simulations", headers=headers, json={
    "topic": "Is remote work better for productivity?",
    "mode": "voting",
    "demographic_preset": "tech_early_adopters",
    "population_size": 100,
    "stance_statement": "Remote work improves employee productivity",
})

result = response.json()
print(f"Status: {result['status']}")
print(f"Results: {result['results']['summary']}")

# List available presets
presets = requests.get(f"{BASE}/presets", headers=headers).json()
print(f"{presets['count']} presets available")

# Launch in background (returns immediately)
curl -X POST https://api.crowdos.ai/api/v1/developer/simulations/async \
  -H "Authorization: Bearer crowd_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "topic": "Should companies mandate return-to-office?",
    "mode": "voting",
    "demographic_preset": "us_general_population",
    "population_size": 500
  }'

# Response: { "id": "sim-abc", "status": "pending",
#   "poll_url": "/api/v1/developer/simulations/sim-abc/status",
#   "results_url": "/api/v1/developer/simulations/sim-abc" }

# Poll until complete
curl -H "Authorization: Bearer crowd_YOUR_API_KEY" \
  https://api.crowdos.ai/api/v1/developer/simulations/SIM_ID/status

# Fetch full results once status is "complete"
curl -H "Authorization: Bearer crowd_YOUR_API_KEY" \
  https://api.crowdos.ai/api/v1/developer/simulations/SIM_ID

const API_KEY = "crowd_YOUR_API_KEY";
const BASE = "https://api.crowdos.ai/api/v1/developer";

// Run a simulation
const response = await fetch(`${BASE}/simulations`, {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    topic: "What do consumers think about subscription fatigue?",
    mode: "voting",
    demographic_preset: "millennials",
    population_size: 200,
  }),
});

const { id, status, results } = await response.json();
console.log(`Simulation ${id}: ${status}`);
console.log("Summary:", results.summary);

// Each agent's response includes their persona + reasoning
for (const agent of results.agents.slice(0, 3)) {
  console.log(`${agent.name} (${agent.sentiment}): ${agent.reasoning}`);
}

Every study targets a demographic preset — a statistically grounded population model calibrated against published distributions (US ACS 2023, UK ONS 2021, AU ABS 2021) with OCEAN trait distributions from Rentfrow 2008 and Schmitt 2007.

23 country-level starter templates ship by default; the custom-audience filter narrows any of them by geography, age range, gender, interests, income — as affluence tiers or real amounts in local currency — and, on multi-ethnic markets, ethnicity and religion. Enumerate the templates via GET /developer/presets or reference this selection:

Demographic presets give you a population baseline. Custom audience narrows that panel by any combination of geography, age, gender, income tier, and IAB-taxonomy interest. The preset still seeds persona generation; the filter then keeps only personas matching your spec.

Pass custom_audience as a JSON object on any POST /developer/simulations or /simulations/asyncrequest. All fields are optional — omit anything you don't want to filter on.

# Browse the IAB Tech Lab Audience Taxonomy 1.1 (no auth required)
curl https://api.crowdos.ai/api/v1/audience/taxonomy

# Live-preview how many agents match a targeting spec.
# No LLM calls — pure-Python filter against a sampled persona pool.
curl -X POST https://api.crowdos.ai/api/v1/audience/estimate-reach \
  -H "Content-Type: application/json" \
  -d '{
    "preset_key": "us_general_population",
    "sample_size": 500,
    "targeting": {
      "countries": ["US"],
      "regions": ["CA", "NY", "TX"],
      "age_min": 25,
      "age_max": 44,
      "genders": "all",
      "interests": ["technology", "investing-and-stocks"],
      "interest_exclusions": ["gambling"],
      "income_min_tier": 5,
      "income_max_tier": 7
    }
  }'

# Response shape:
# {
#   "matched_count": 187,            # personas that passed the filter
#   "sample_total": 500,             # personas we tested
#   "match_rate": 0.374,              # matched_count / sample_total
#   "confidence": "medium",           # low | medium | high (sample-size)
#   "by_dimension": { ... }           # breakdown by country/age/etc.
# }

# Field a sim against a narrowed audience.
# Adding custom_audience filters the panel beyond the preset baseline.
# Personas are still SEEDED by demographic_preset; the filter then
# keeps only those matching the spec.
curl -X POST https://api.crowdos.ai/api/v1/developer/simulations \
  -H "Authorization: Bearer crowd_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "topic": "Would you switch banks for a 5% APY savings account?",
    "mode": "voting",
    "demographic_preset": "us_general_population",
    "population_size": 200,
    "custom_audience": {
      "countries": ["US"],
      "age_min": 30,
      "age_max": 55,
      "genders": "all",
      "interests": ["personal-finance", "investing-and-stocks"],
      "income_currency": "USD",
      "income_min_amount": 150000
    }
  }'

import requests

API_KEY = "crowd_YOUR_API_KEY"
BASE = "https://api.crowdos.ai/api/v1/developer"
ROOT = "https://api.crowdos.ai"
headers = {"Authorization": f"Bearer {API_KEY}"}

# 1. Discover interest tags (unauthenticated)
taxonomy = requests.get(f"{ROOT}/api/v1/audience/taxonomy").json()
# taxonomy["categories"] = { "automotive": [...], "technology": [...], ... }

# 2. Preview reach before committing
preview = requests.post(f"{ROOT}/api/v1/audience/estimate-reach", json={
    "preset_key": "us_general_population",
    "sample_size": 500,
    "targeting": {
        "countries": ["US"],
        "age_min": 22,
        "age_max": 35,
        "interests": ["video-gaming", "technology"],
        "income_min_tier": 6,
    },
}).json()
print(f"~{preview['match_rate']*100:.1f}% match rate, confidence={preview['confidence']}")

# 3. Field the study with custom_audience
sim = requests.post(f"{BASE}/simulations", headers=headers, json={
    "topic": "Should game studios charge $70 for AAA titles?",
    "mode": "voting",
    "demographic_preset": "us_general_population",
    "population_size": 200,
    "custom_audience": {
        "countries": ["US"],
        "age_min": 22,
        "age_max": 35,
        "interests": ["video-gaming", "technology"],
        "income_min_tier": 6,
    },
}).json()
print(sim["results"]["summary"])

GOTCHAS

• Preview reach before paying. A narrow filter may match few respondents; the panel is grown from your closest real matches rather than faked. POST /audience/estimate-reach is free and names the constraint that cuts hardest; the delivered count is results.agent_count.
• Interests are exact tags. Use the slug strings from GET /audience/taxonomy — “personal-finance”, not “Personal Finance”. Matching is case-insensitive but the tag itself must exist.
• Income tiers are relative; amounts are literal. Tiers pick the same affluence standing in every market's own income ladder. To target by real earnings instead, send income_currency + income_min_amount (and optionally income_match: "absolute").
• JSONB cap: 16 KB. If you're passing hundreds of interests / regions / cities, group them by preset and field multiple smaller studies instead.

Fielding duration:A 20-respondent Pulse study typically completes in 5–15 seconds. Panels at scale (200+ respondents) typically field in 30–120 seconds. For large populations, use POST /simulations/async which returns immediately, then poll GET /simulations/{id}/status until complete. Rate-limited requests receive a 429 with a Retry-After header.