screen_creatives
Screen videos or images in Screening Room, as on the web: every respondent watches or looks at each creative itself, scores and ranks them, and says what works in the creative (message, hook, visuals, pacing, copy, call to action). One creative is a solo review; two or more are ranked against each other. You get the ranking or the solo verdict, a synthesis memo and, on the deeper tiers, expert reports and a debate summary, without individual answers.
Pick a tier; each fields the panel the web sells: quick_pulse (Quick Review, 35 respondents), balanced_insight (Balanced Insight, 150, the default), deep_research (Deep Review, 400). Your plan screens up to 2 creatives per study (Free 2, Pro 3, Max 4). Every plan can run every tier.
Pass each creative as a public https link straight to the file (PNG/JPG/WEBP/GIF up to 10 MB, MP4/MOV/WebM/AVI/MKV/M4V up to 100 MB) that opens without signing in, not a page that shows it; a link that returns a web page is refused before anything is charged.
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. Price it with preview_cost(mode='comparison', comparison_tier, num_options).
Takes minutes; the tool waits up to ~15 minutes and reports progress. On error='timeout' with a sim_id the study keeps running: collect it with get_simulation, do not re-run.
Returns: { id, status, mode='comparison', topic, demographic_preset, population_size, screening_room: {tier, tier_label}, options, winner and leaderboard (2+ creatives), solo_summary (one creative), synthesis_memo, expert_reports [{lens, report}], debate_summary (Deep Review), total_responses, billing }.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| media | Yes | The creatives, in order (option A is the first): 1 for a solo review, up to 2 to rank (Free 2, Pro 3, Max 4). | |
| topic | Yes | What the viewers are asked, e.g. 'Which ad makes you most likely to try the app?' or, for one creative, 'Would this ad make you stop scrolling?' | |
| 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 |
| comparison_tier | No | Depth: quick_pulse (35 respondents), balanced_insight (150, expert reports; the default), deep_research (400, expert reports and a debate). | balanced_insight |
| 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. | |
| demographic_preset | No | Audience preset. Use list_demographic_presets to see all options. Default: us_general_population. | us_general_population |