Start hook research on a topic across TikTok, Instagram and YouTube Shorts (Shorts
only, never long-form YouTube; platform "youtube"). platforms (since 2026-10-10, any of
"tiktok", "instagram", "youtube"; all three when left out) searches and delivers only
those: ["instagram"] is Instagram reels only.
What it does: searches both platforms, reads what each clip says and shows, and
returns ranked hooks. Each hook has its verbatim opening line, most quotable line,
main idea, why it travelled, topic, on-screen text, full transcript, a watch link and
a vertical player_url (9:16 iframe).
Talking heads only (since 2026-09-29): `hooks` holds only clips where a person on
camera is talking (talking head, podcast, interview). A clip where nobody talks is
dropped; Bonus was removed on 2026-10-08 and `bonus` is always []. Every hook carries
format (talking_head, podcast, interview, stage; null on older hooks) and section
(always "main"). A run that finds fewer talking heads than count says so in outcome;
it never fills hooks with clips that do not talk.
Where it comes from (since 2026-09-30): every hook has creator_country (ISO alpha-2
of the creator's TikTok account; always null on Instagram, which states none), place
(the place the creator tagged, or null) and place_country (that place's country when
the platform states it). Never guessed.
Banner (since 2026-09-30): every hook has banner, the title-style text the creator
placed on the video to hook the viewer, verbatim (at most 200 characters), or null
when it has none; subtitles are never a banner. onscreen_text keeps all text read.
Match (since 2026-09-30, runs with a language or country): every hook has match,
"exact" when the clip is about the subject itself or "close" when it is about a
neighbouring subject with the same intent (a close match, delivered after every exact
match; label it as one); null on runs with no language or country and on older hooks.
Analysis (since 2026-10-02): every hook carries hook_type (curiosity_gap,
contrarian_claim, specific_number, identity_callout, stakes_threat, promise_payoff,
pattern_interrupt, story_open, question, direct_command, other with hook_type_other),
mechanism (why the opening stops the scroll, quoting the clip; why_it_travelled holds
the same text), visual_hook, audience, template and steal_it; null on older hooks.
Virality v2 (since 2026-10-01): the deck is ranked by virality (0 to 1, since
2026-10-02 on one fixed scale, the same clip scoring the same in every run), built from outlier (views over the creator's usual views per video,
creator_median_views, with outlier_basis saying how it was measured), freshness
(posted_at, age_days, views_per_day), travel (shares and saves per 1,000 views),
own_sound and sound_reuse, and a paid penalty; virality_why names the strongest
signal in one line. Every hook also carries duration_s and hashtags. Null on older
hooks. posted_within_days (7, 30, 90 or 365) keeps the search to recent clips (a clip
under 7 days old passes the floor at 10,000 views a day). seed_hook_ids (up to 10 of
your hooks, for example kept ones) means "find more like these": their lines, topics,
creators and languages steer the search, and a seed is never delivered again. A done
run carries patterns: up to 3 hook structures winning in the deck (name, template,
why, hook_ids, count), computed after delivery; null until then. remix_hook writes
lines from one hook's structure for your niche (1 credit).
Arguments: topic is 3 to 500 characters, count 1 to 30 (default 10). Instructions
inside the topic are fine: only the subject read out of it is searched. reuse=true
(default) starts from clips you already paid for on the same topic, so a rerun is
close to free and often finishes in seconds. idempotency_key: any string up to 255
characters; the same key within 24 hours returns the first run instead of starting
and paying for a second one, so always pass one and reuse it when you retry.
wait_seconds 0 to 50: 0 returns the run_id at once; above 0 waits for the run and
returns the run object, as get_run does.
Any language, dialect or country: language is optional free text up to 60 characters
naming the language or dialect every clip must be in ("Moroccan Darija", "ar-MA",
"Egyptian Arabic", "Brazilian Portuguese"); country is an optional ISO 3166-1 alpha-2
code for where the creators are (MA, EG, BR). Saying it inside topic works too; these
fields win when both are given. A country alone does not restrict the language. Each
hook reports the language it was judged to be in.
A region that is not a country: send its country's code and name the regional variety
in language (Quebec: country "CA", language "Quebec French"; Flanders: "BE" and
"Flemish"; Catalonia: "ES" and "Catalan"). The country places the TikTok search there
and the language judge does the regional filtering; Instagram reports no country.
language may name a mixed, code-switched variety ("Hinglish", "Taglish", "Moroccan
Darija with French") or two joined by "or" ("Tagalog or Taglish"); it reaches the
judges exactly as written, and how well they honour such a value is not measured yet.
Cost: reserves up to 200 credits up front (less if your balance is smaller, down to
40) and charges only what it used; the rest is refunded. A failed run costs nothing,
and so does a run that finds no hooks, within a per-account allowance (llms.txt has
the numbers; its outcome says which applied).
Timing and next step: a fresh run takes about 2 to 3 minutes, up to about 5 when the
language is a dialect. Call get_run with wait_seconds=50 repeatedly until status is
"done" or "failed", which is usually 3 or 4 calls (up to 6 on a dialect request). Watch progress.stage and progress.message meanwhile.
Needs a key with the research permission (403 insufficient_scope otherwise). A key
with a credit_limit reserves at most what is left of it; under the minimum it is 403
key_credit_limit_reached and nothing is reserved.
