compare_options
Run a simulated A/B (or A/B/C…) test (a Pulse compare) on text options. Each respondent reads every option and ranks them; you get a leaderboard with Borda scores and the winner, without individual answers. Use it for product descriptions, headlines, policy framings, slogans or value propositions.
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). Your plan compares up to 3 options (Free 3, Pro 5, Max 10).
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.
Returns: { id, status, mode='comparison', topic, demographic_preset, population_size, options, winner, leaderboard (first_place_votes, vote_pct, borda_score, borda_pct, scores {mean, n, positive_pct, neutral_pct, negative_pct} of each option's 0-10 scores), counted_agent_count, breakdowns (each option's first-choice share and mean score by age_band, gender, political_ideology, region and, where respondents carry their market's party lean, party), [undecided] (when respondents could choose none of the options: an election or referendum question, or undecided_option; each leaderboard row then adds decided_vote_pct), total_responses, billing }.
Read first-choice shares as a direction, beside each option's scores, not as a market share. WHEN IT MISLEADS: options described unevenly (one with its costs or limits spelled out, the others with strengths only; some priced, others not), or a panel of the whole market read as a survey of buyers. Pass the draft to preview_cost first: its brief_warnings flag these.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| topic | Yes | The question framing the comparison, e.g. 'Which of these product descriptions resonates most with you?' | |
| 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. | |
| options | Yes | 2-3 text options to compare, each up to 500 characters (Free 3, Pro 5, Max 10). | |
| language | No | Language the respondents answer in. Default: en. | en |
| image_url | No | Optional public HTTPS URL of an image every respondent considers while ranking the options (a product photo, the ad the headlines go with). Same shape as run_focus_group.image_url. | |
| 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). | |
| undecided_option | No | Whether respondents may choose none of the options (undecided, would not vote). Omit it and it is on for an election or referendum question and off otherwise. When on, the result adds undecided {first_choice_pct, respondents, chance_pct, chance_respondents} and each leaderboard row a decided_vote_pct. | |
| demographic_preset | No | Audience preset. Use list_demographic_presets to see all options. Default: us_general_population. | us_general_population |