wait_seconds 0 to 50: wait up to that long for the run to finish, returning the
moment it is done or failed. Use wait_seconds=50 and call again while status is
"queued" or "running"; a fresh run needs about 3 or 4 such calls. progress has
stage, message and updated_at, plus counts once the research reports them, preview
(hooks written so far) while a running run holds one, and feed (the live research
wall: up to 24 clips the run is working on, newest first, each key, platform, creator,
views, state found|reading|talking|passed, thumb_url, a JPEG any <img> can load
with no key, and line, the banner or opening words once the judges passed the clip)
while it shows one, and on a Long form or Packaging run scan (the videos it is looking
at: up to 60 tiles {v: YouTube video id, s: found|on_topic|off_topic|measured|beat|
reading|ready|passed, x: multiple of the channel's usual or null}, oldest first, and
lanes with found, on_topic, measured, beat, reading, ready; draw a tile from
https://i.ytimg.com/vi/{v}/mqdefault.jpg; counts.measured and counts.beat are the
numbers report.landscape ends on). Pass since with the last
progress.updated_at to return on change or completion. It must be an ISO timestamp
with a timezone (422 invalid_request otherwise). `hooks` is the deck (a person
talking); `bonus` is always [] (removed 2026-10-08). Every hook has format and
section (always "main"), and
creator_country (TikTok only), place and place_country (null when unknown), banner
(the title placed on the video, null when none) and match ("exact" or "close", a
close match being a neighbouring subject delivered after the exact ones; null on runs
with no language or country and on older hooks). Since 2026-10-04 the run carries
understood (what the request was read to ask: subject, language, country, core,
audience, neighbours, styles, style_other, wants; null until read) and, on a run that
asked for a kind of opening ("controversial hooks", "storytime"), every hook carries
style_match (true when it opens that way; null otherwise). Since 2026-10-01 every hook carries
the virality v2 fields: virality (0 to 1 on one fixed scale since 2026-10-02),
virality_why, outlier, outlier_basis, creator_median_views, posted_at, age_days,
views_per_day, duration_s, paid, sound_reuse, own_sound, hashtags (null on older
hooks), and since 2026-10-02 the analysis: hook_type, hook_type_other, mechanism,
visual_hook, audience, template, steal_it; the run echoes posted_within_days and
seed_hook_ids, and once done carries
patterns: up to 3 hook structures winning in this deck, each name, template, why,
hook_ids and count, grouped by hook_type and computed before the run is done, in the
deck's language (null on older runs and when nothing is shared). Hooks include
transcript_kind:
speech, music, none, other, or null when unknown; and heard: false when our speech
service could not hear the clip right now (no spoken words shown, transcript null; the
done message then counts them), true otherwise. conversation_id names the chat conversation the run
belongs to (null outside one). A done run with fewer hooks than asked for, or none,
has outcome: why in one plain paragraph, what to try next, and whether it was free
(stats.rejections holds the counts); a full run's outcome is null, or one sentence
when some hooks are under the view floor because the country filter set clips aside.
Free: reading a run costs no credits.