run_focus_group
Run a simulated focus group (a Pulse vote) on a question, policy, product idea or stance. Respondents are drawn from a demographic preset; you get the sentiment totals (counts and shares, no individual answers). Blocks about 5-120 seconds depending on population_size.
RECOMMENDED FLOW: if the user didn't pick an audience, call list_demographic_presets and propose one or two; call preview_cost for the price; confirm with the user; then run. Studies are charged to the account's wallet at the same per-respondent rate as on the web.
Your plan allows up to 20 respondents per study (Free 20, Pro 500, Max 1,000). On error_type=over_plan_cap, retry with the limit named in the error.
To target inside a market (age band, cities, income, interests, ethnicity), pass custom_audience and preview it for free with estimate_reach first.
To show respondents an image with the question (a product photo, a chart, a screenshot), pass image_url: a public https link to it. To have them watch videos or look at images as creatives, use screen_creatives; to test an ad in the feed, use test_ads.
WHEN IT FITS: one proposition, read as how a market feels about it (agree or disagree with a stance_statement, or the mood around a topic). WHEN IT MISLEADS: a question that asks people to pick between options. A vote records feelings, never picks; use compare_options.
Returns: { id, status, mode='voting', topic, demographic_preset, population_size, sentiment_summary: { positive, neutral, negative, positive_pct, neutral_pct, negative_pct }, counted_agent_count (the respondents whose answers were counted), breakdowns (the same split by age_band, gender, political_ideology, region and, where respondents carry their market's party lean, party; a group under min_group_size shows only its size), total_responses, billing }. If you gave a stance_statement, sentiment_axis says what positive and negative mean (Agree / Disagree).
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| topic | Yes | The question or subject to test, e.g. 'Should the federal minimum wage be $20/hr?'. With a stance_statement, respondents read the statement and, under it, this topic whenever it adds to it. | |
| context | No | Background every respondent reads before answering: a product description, the ad copy, a news story, the terms of an offer. Plain text, up to 16,000 characters. The result's shown_to_respondents block echoes what the panel read. | |
| language | No | Language the respondents answer in. Default: en. | en |
| image_url | No | Optional public HTTPS URL of an image to attach to the question. One vision call extracts a description that every text-only agent reacts to alongside the question — useful for testing diagrams, product photos, charts, screenshots, or political imagery. Adds ~1-3s to the run regardless of population_size. | |
| custom_audience | No | Optional filter narrowing the panel INSIDE the market preset. Keys (all optional): countries, regions, cities (each market's own vocabulary), age_min / age_max, genders ('all' | 'men' | 'women' | 'non_binary'), interests / interest_exclusions (taxonomy tags), income_min_tier / income_max_tier (affluence ladder 0-7, 7 = top), income_currency + income_min_amount / income_max_amount (REAL annual household amounts in a named ISO currency — currency is required with amounts; e.g. {'income_currency': 'USD', 'income_min_amount': 100000}), income_match ('position' = the equivalent affluence standing within each market's own income ladder, the default; 'absolute' = actual earnings at indicative FX), ethnicities / religions (multi-ethnic markets only). Preview a custom_audience with the free estimate_reach tool before paying for a run — it reports the audience size and which constraint cuts hardest. A 'small' audience is not a blocker: the panel is still delivered at the population_size you ask for, with every respondent matching the filter, and its age and gender mix follows the market's profile within the filter's age, gender, place, income and heritage terms (interest tags pick who within each group, not how many of each). Results carry panel_check (the panel's age, gender and region mix against that profile) and, for an uncommon audience, audience_note. Guide: https://crowdos.ai/mcp. | |
| population_size | No | Respondents. Default 20. Your plan's limit is 20 (Free 20, Pro 500, Max 1,000). | |
| stance_statement | No | Optional declarative the agents take a position FOR or AGAINST. Improves clarity on comparison questions. | |
| demographic_preset | No | Audience preset. Use list_demographic_presets to see all options. Default: us_general_population. | us_general_population |