preview_cost
Estimate the cost (credits) and runtime (seconds) of a hypothetical run_focus_group, run_debate, compare_options, screen_creatives or test_ads call WITHOUT actually running it. Use this when you need to budget before committing — autonomous agents should preview before any sim with population_size > 100 or any debate at all.
Free to call (no wallet debit, no rate-limit penalty beyond the regular per-key limit). Pricing is a fixed rate per respondent. Returns: estimate_credits, min_credits and max_credits (the figures below in credits — quote these to the user), estimate_cents (what a real run reserves — a completed vote is charged exactly this), min_cents / max_cents (the settle range: a debate may settle lower if it reaches consensus early, down to min_cents; respondents who fail to answer are never charged), expected_seconds_min / expected_seconds_max (so you can set a sensible tool-call timeout), plan, agent_cap, and within_agent_cap (false means the population_size exceeds the user's plan limit and the real call would 400).
BRIEF CHECK: also pass the draft brief (topic, the options for a comparison, demographic_preset and custom_audience as you plan to run them) and the result adds brief_warnings, a list of { code, message, options?, compared_with?, phrase? }. Codes: choice_question_in_vote (a vote or debate that asks people to pick between options — use compare_options), election_question_in_vote (a vote or debate on an election or referendum — use compare_options with each candidate or answer as an option), election_question (a compare_options run on an election or referendum — name each candidate's party in its option and ask whom respondents would vote for), one_sided_option (some options state a cost or limit and others state none), uneven_prices (some options carry a price and others none), missing_prices (the question asks about buying and no option has a price), audience_fit (the question assumes something, such as a next car or a job, that the audience is not narrowed to). Option letters: A is the first. Show the notes to the user before running; they never block a run, and the user decides whether to change the brief.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | Which study to price: voting (one pass), debate (priced per round), comparison (priced like a vote; send the options to have them checked) or ad_lab (a test_ads study, priced per respondent however many creatives). Default: voting. | voting |
| topic | No | Optional: the question you plan to ask. With it the result adds brief_warnings. | |
| options | No | Optional, comparison: the text options you plan to rank, in order. | |
| num_rounds | No | Debate-only. Default 5 to match run_debate's platform-standard default. Ignored for voting. | |
| num_options | No | With comparison_tier: how many creatives you will screen (1-4). | |
| comparison_tier | No | To price a screen_creatives study: its tier, with mode='comparison' and num_options. The quote is for the tier's panel (35 / 150 / 400); leave population_size out. | |
| 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 | The panel to price. Your plan's limit is 20 respondents (Free 20, Pro 500, Max 1,000); an Ads Labo study (mode='ad_lab') takes 100, 200, 400 or 1,000 on every plan. | |
| stance_statement | No | Optional: the statement a vote will ask respondents to agree or disagree with. | |
| demographic_preset | No | Optional: the market preset you plan to run. |