find_hooks

com.hookdetector/hookdetector · Verify this server

Start hook research on a topic across TikTok, Instagram and YouTube Shorts (Shorts only, never long-form YouTube; platform "youtube"). 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 and bonus (since 2026-09-29): `hooks` holds only clips where a person on camera is talking (talking head, podcast, interview). The run object also has `bonus`: its best clips without talking (text on screen, voiceover, b-roll with captions), in the same hook shape, up to count and at least half of it when the run read that many. Bonus is free. Every hook carries format (talking_head, podcast, interview, voiceover, text_on_screen, broll, skit, other; null on older hooks) and section ("main" or "bonus"). 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 5 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.