Hook Detector

Quality 72 / 100needs work

43 tools, about 18,271 tokens to load them all · tool set 710b89aa7827 · tools last changed 2026-10-12 · checked 2026-10-19 10:52 UTC

Tool changes

• 2026-10-12keep_hookchangeddescription, input schema
  before

  Keep or reject a hook: verdict is "keep" (default) or "reject", and the last verdict wins. Kept hooks come back from list_keeps, across all runs. Free.

  after · 50% of words in common

  Keep or reject a hook: verdict is "keep" (default) or "reject", and the last verdict wins. A reject may say why: reason is off_subject, weak_opening, wrong_language, low_quality, already_have or other, and note (up to 280 characters) your own words. Kept hooks come back from list_keeps, across all runs. Free.

• 2026-10-12get_runchangeddescription
  before

  A research run: its status, progress, charge and every hook it produced. 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 5 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. 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.

  after · 100% of words in common

  A research run: its status, progress, charge and every hook it produced. 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. 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.

• 2026-10-12find_hookschangeddescription
  before

  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 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; th

  after · 100% of words in common

  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; th

• 2026-10-10chatchangedinput schema
• 2026-10-10find_hookschangeddescription, input schema
  before

  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 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 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:

  after · 99% of words in common

  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 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; th

• 2026-10-09remix_hookchangeddescription, input schema
  before

  Make it mine: write up to n new opening lines (1 to 5, default 3) for your niche that keep a real hook's structure, the device that made it travel, with the subject swapped for yours. hook_id is one of your hooks (from get_run, get_hook or list_keeps); 404 hook_not_found otherwise. Returns {"hook_id", "niche", "n", "written": [{"line", "kept_structure"}], "label", "credits_charged": 1, "credits"}. label is always "Written by Hook Detector from a real hook's structure": these are written lines, never found hooks; show the label with them, never present one as a real clip's hook. They are never added to a deck, a keep or an export. Costs 1 credit per call, taken before the model is asked and refunded when it does not answer (503 model_unavailable) or when nothing it wrote keeps the rules or it declines the content (422 remix_not_possible, the reason in the message; another try or another niche may work). 402 insufficient_credits at a balance of 0; limited per account per hour (429 rate_limited). Needs the research permission. The answer carries remix_id: list_remixes and get_remix read it back, free. Same as POST /v1/hooks/{hook_id}/remix.

  after · 91% of words in common

  Make it mine: write up to n new opening lines (1 to 5, default 3) for your niche that keep a real hook's structure, the device that made it travel, with the subject swapped for yours. hook_id is one of your hooks (from get_run, get_hook or list_keeps); 404 hook_not_found otherwise. Leave mode out: "intro" (Write my intro) is remix_find on a long-form find, and is 422 here, before any charge. Returns {"hook_id", "niche", "n", "written": [{"line", "kept_structure"}], "label", "credits_charged": 1, "credits"}. label is always "Written by Hook Detector from a real hook's structure": these are written lines, never found hooks; show the label with them, never present one as a real clip's hook. They are never added to a deck, a keep or an export. Costs 1 credit per call, taken before the model is asked and refunded when it does not answer (503 model_unavailable) or when nothing it wrote keeps the rules or it declines the content (422 remix_not_possible, the reason in the message; another try or another niche may work). 402 insufficient_credits at a balance of 0; limited per account per hour (429 rate_limited). Needs the research permission. The answer carries remix_id: list_remixes and get_remix read it back, free. Same as POST /v1/hooks/{hook_id}/remix.

• 2026-10-09remix_findchangeddescription, input schema
  before

  Make it mine, for a long-form opening or a package: write up to n (1 to 5, default 3) new ones for your niche that keep one real find's structure. From a long find, `written` holds openings: hook (what the creator says first), then (what the next half minute has to deliver) and kept_structure, built on the find's template and its order of beats. From a packaging find it holds packages: title, thumbnail (what to show and how to frame it), thumbnail_text (the words to print, or null) and kept_structure, built on its title template and its thumbnail's composition. Returns {"find_id", "kind", "niche", "n", "written", "label", "credits_charged": 1, "credits"}. label says they were written by Hook Detector from a real opening's (or package's) structure: show it with them, never present one as a real video's. One that is the real find's own words is dropped. They are never added to a run, a keep or an export. Costs 1 credit per call, taken before the model is asked and refunded when it does not answer (503 model_unavailable) or when nothing it wrote keeps the rules or it declines the content (422 remix_not_possible, the reason in the message; another try or another niche may work). 402 insufficient_credits at a balance of 0; 404 find_not_found; limited per account per hour (429 rate_limited). Needs the research permission. The answer carries remix_id: list_remixes and get_remix read it back, free. Same as POST /v1/finds/{find_id}/remix.

  after · 80% of words in common

  Make it mine, for a long-form opening or a package: write up to n (1 to 5, default 3) new ones for your niche that keep one real find's structure. From a long find, `written` holds openings: hook (what the creator says first), then (what the next half minute has to deliver) and kept_structure, built on the find's template and its order of beats. From a packaging find it holds packages: title, thumbnail (what to show and how to frame it), thumbnail_text (the words to print, or null) and kept_structure, built on its title template and its thumbnail's composition. Write my intro: with mode "intro" and video_brief (your own video in a few sentences, 10 to 600 characters; a long find only, a packaging find is 422; niche and n are not used) it writes YOUR intro in the real opening's structure. `written` then holds one object with a beat for each beat of the real opening, in order: beat, does, from_s, to_s, seconds and words_budget (the real opening's own timing, never the model's), say (the words to say, with {placeholders} for what only you know), words, placeholders, suggested_on_screen and suggested_broll (suggestions, never part of what is said); and seconds, timing (measured or estimated), kept_structure, placeholders and numbers_to_placeholders. The answer carries mode "intro" and video_brief, and niche is null. A number you did not write in video_brief becomes {number}. One that copies the real opening or runs over a word budget is 422 remix_not_possible. Returns {"find_id", "kind", "niche", "n", "written", "label", "credits_charged": 1, "credits"}. label says they were written by Hook Detector from a real opening's (or package's) structure: show it with them, never present one as a real video's. One that is the real find's own words is dropped. They are never added to a run, a keep or an export. Costs 1 credit per call, taken before the model is asked and refunded when it does not answer (503 model_unavailable) or when nothing it wrote keeps the rules or it declines the content (422 remix_not_possible, the reason in the message; another try or another niche may work). 402 insufficient_credits at a balance of 0; 404 find_not_found; limited per account per hour (429 rate_limited). Needs the research permission. The answer carries remix_id: list_remixes and get_remix read it back, free. Same as POST /v1/finds/{find_id}/remix.

• 2026-10-09find_packagingchangeddescription, input schema
  before

  Find packaging: the titles and thumbnails that earned the click on a topic, from long-form YouTube videos that beat their own channel. What it does: runs the same outlier search as find_long_hooks (long-form YouTube, 2023 or later, views at least min_outlier times the channel's usual), then looks at each video's thumbnail beside its title and says what the pair is doing. What comes back: the run's `finds`, ranked. Each is a real package, as YouTube shows it: title (verbatim) and thumbnail_url (the size YouTube really served, the picture the analysis looked at; thumbnail_checked says so), channel, watch_url, views, channel_median_views, outlier, outlier_score (0 to 100 on one fixed scale, so finds from different runs rank together), outlier_tier, channel_size and posted_at, plus the analysis: title_device (curiosity_gap, contrarian_claim, specific_number, how_to, listicle, challenge, story, question, warning, comparison, authority, timeliness, identity_callout, other), title_template (the title as a fill-in structure), thumbnail_text (the words printed on the thumbnail, read by a vision model; null when none), thumbnail_text_role (repeats_title, adds_to_title, contrasts_title, no_text), thumbnail_subject, thumbnail_faces, thumbnail_emotion, thumbnail_colors, thumbnail_composition, thumbnail_devices, angle, gap (what the picture shows that the title does not say, and the question that leaves), promise, steal_it and audience. analysed is false when a package could not be looked at; it is still a real package. The run's report then holds title_patterns and thumbnail_patterns (what at least two of the packages share, each naming their video_ids) and ideas: up to `ideas` (6 by default, 0 for none) packages WRITTEN for your topic from those patterns, each a title a thumbnail concept and thumbnail_text (the words to print on it), naming the real packages it is based_on. report.ideas_label is always "Written by Hook Detector from the patterns in these real packages": show it with them, never present an idea as a real video's title. report.numbers counts the packages: title_chars and title_words (medians), titles_with_number, titles_with_question, thumbnails_with_text and thumbnail_words (over the analysed ones), and the title_devices, thumbnail_devices and emotions that repeat (name, count). report.landscape is the subject at a glance, as on find_long_hooks. Arguments: topic 3 to 500 characters, or a channel's or a long-form video's YouTube address exactly as on find_long_hooks (a channel's own outliers, or that one video; no ideas are written for a link, use remix_find); count 1 to 24 (default 12); language, country, min_outlier, posted_within_days, channel_size and reuse as on find_long_hooks; idempotency_key and wait_seconds as on find_hooks. Cost: reserves up to 70 credits (down to 25) and charges only the provider calls it made: the searches, one call per channel measured, and one for each video whose date had to be read exactly. Looking at a thumbnail costs no credit. After a find_long_hooks run on the same topic it is close to free. A failed run costs nothing, and so does a run that finds nothing, inside the allowance. Timing and next step: how long a run takes has not been measured yet, so never assume a time. Call get_run with wait_seconds=50 until status is done or failed. Same as POST /v1/packaging. Needs the research permission.

  after · 84% of words in common

  Find packaging: the titles and thumbnails that earned the click on a topic, from long-form YouTube videos that beat their own channel. What it does: runs the same outlier search as find_long_hooks (long-form YouTube, 2023 or later, views at least min_outlier times the channel's usual), then looks at each video's thumbnail beside its title and says what the pair is doing. What comes back: the run's `finds`, ranked. Each is a real package, as YouTube shows it: title (verbatim) and thumbnail_url (the size YouTube really served, the picture the analysis looked at; thumbnail_checked says so), channel, watch_url, views, channel_median_views, outlier, outlier_score (0 to 100 on one fixed scale, so finds from different runs rank together), outlier_tier, channel_size and posted_at, plus the analysis: title_device (curiosity_gap, contrarian_claim, specific_number, how_to, listicle, challenge, story, question, warning, comparison, authority, timeliness, identity_callout, other), title_template (the title as a fill-in structure), thumbnail_text (the words printed on the thumbnail, read by a vision model; null when none), thumbnail_text_role (repeats_title, adds_to_title, contrasts_title, no_text; counted from title_overlap, the share of the thumbnail's words that are also in the title, where that can be), thumbnail_subject, thumbnail_faces, thumbnail_emotion, thumbnail_colors, thumbnail_composition, thumbnail_devices, angle, gap (what the picture shows that the title does not say, and the question that leaves), promise, steal_it and audience, plus cut_on_phone (the title is longer than 60 characters, where a phone roughly cuts it; approximate) and on_subject (yes or partly: whether the look judged the package to be about your topic; a package judged not to be is dropped and the next one takes its slot; null on a link run). analysed is false when a package could not be looked at (its look is asked twice, and the next candidate takes the slot if it fails twice); it is still a real package. The run's report then holds title_patterns and thumbnail_patterns (what at least two of the packages share, each naming their video_ids) and ideas: up to `ideas` (6 by default, 0 for none) packages WRITTEN for your topic from those patterns, each a title a thumbnail concept and thumbnail_text (the words to print on it), naming the real packages it is based_on. report.ideas_label is always "Written by Hook Detector from the patterns in these real packages": show it with them, never present an idea as a real video's title; an idea over 70 characters, with more than 5 words for its thumbnail or repeating a real title is dropped. report.numbers counts the packages: title_chars and title_words (medians), titles_with_number, titles_with_question, titles_cut_on_phone (with phone_title_chars, the approximate length a phone cuts a title at), thumbnails_with_text and thumbnail_words (over the analysed ones), and the title_devices, thumbnail_devices and emotions that repeat (name, count); age_cohorts repeats the counts for packages posted in the last split_days days (recent) and for older ones, with the undated apart. report.landscape is the subject at a glance, as on find_long_hooks. Arguments: topic 3 to 500 characters, or a channel's or a long-form video's YouTube address exactly as on find_long_hooks (a channel's own outliers, or that one video; no ideas are written for a link, use remix_find); count 1 to 30 (default 12); language, country, min_outlier, posted_within_days, channel_size and reuse as on find_long_hooks; idempotency_key and wait_seconds as on find_hooks. Cost: reserves up to 70 credits for 24 packages or fewer and 3 more for each package above that (88 at 30; down to 25) and charges only the provider calls it made: the searches, one call per channel measured, and

• 2026-10-09find_long_hookschangeddescription, input schema
  before

  Find long-form hooks: how the YouTube videos that beat their own channel open, on a topic. Long-form YouTube only, never Shorts, TikTok or Instagram (for those: find_hooks). What it does: searches YouTube for long-form videos on the topic, keeps only the outliers (a video whose views are at least min_outlier times the median views of its own channel's recent uploads; 2 by default) posted in 2023 or later (nothing older is ever delivered), reads the first intro_seconds (60 by default) of each one's transcript, and says why that opening holds a viewer. What comes back: the run's `finds`, ranked, strongest outlier first. Each has title, channel, watch_url, player_url (an iframe src), thumbnail_url, views, channel_median_views, outlier (28.2 means 28 times the channel's usual), outlier_score (0 to 100 on one fixed scale: nothing else a run found moves it, so finds from different runs rank together), outlier_tier, channel_size, likes_per_1k, posted_at, duration_s, and the opening: hook (the lines that stop a viewer leaving, verbatim), hook_seconds, intro (the first minute as it was said: lines of n, t in seconds, text) and intro_text. The analysis: hook_type (the same list as find_hooks), mechanism (why it holds, quoting the opening word for word), promise, open_loop, title_link (how the first lines pay off the title), beats (the opening in parts: from, to, beat, does), opens_with (cold_open, greeting, teaser, question, sponsor), format (the kind of video), angle, template (the hook as a fill-in structure), steal_it and audience. When the topic asks for a kind of opening ("question hooks", "storytime"), style_match says whether each find is that kind and the matches come first. analysed is false when the model could not analyse an opening: the opening is still real, its analysis fields are null. The run's report.patterns lists the opening types at least two finds share; report.shape says how the openings are built, counted from the finds (hook_seconds and hook_words as medians, beats with how many openings use each and the second it usually starts_at, and the sequence of beats most of them share); and report.openers holds up to `openers` (3 by default, 0 for none) openings WRITTEN for your topic from those structures (hook, then, hook_type, based_on). report.openers_label is always "Written by Hook Detector from the structure of these real openings": show it with them, never present one as a real video's opening. report.landscape is the subject at a glance, counted from the videos the run held against their own channel (videos, channels, outliers and their share, breakouts, small_channel_outliers, recent_outliers). The run's hooks and bonus are always empty. A link instead of a subject: when topic is a channel's YouTube address (https://www.youtube.com/@name, or just @name) the run returns that channel's OWN outliers, its recent long-form uploads that beat its usual (one provider call, no search); when it is a long-form video's address the run returns that one video, whatever its multiple (requested is 1). options.link says "channel" or "video". No openings are written for a link (use remix_find on a find to write for your niche). A Short's address is refused with 422. Arguments: topic 3 to 500 characters; count 1 to 20 (default 8); language and country optional; posted_within_days 30, 90, 365 or 730 to narrow the 2023 floor further; channel_size "small", "medium" or "large" to keep only channels of that size (by what their uploads usually get), so a small creator sees breakouts from channels their own size; reuse=true (default) starts from the videos your last long or packaging run on this topic bought within a week, and a video you already had read is delivered from that read (analysis_from_earlier_read) at no model or provider cost. seen_before

  after · 92% of words in common

  Find long-form hooks: how the YouTube videos that beat their own channel open, on a topic. Long-form YouTube only, never Shorts, TikTok or Instagram (for those: find_hooks). What it does: searches YouTube for long-form videos on the topic, keeps only the outliers (a video whose views are at least min_outlier times the median views of its own channel's recent uploads; 2 by default) posted in 2023 or later (nothing older is ever delivered), reads the first intro_seconds (60 by default) of each one's transcript, and says why that opening holds a viewer. What comes back: the run's `finds`, ranked, strongest outlier first. Each has title, channel, watch_url, player_url (an iframe src), thumbnail_url, views, channel_median_views, outlier (28.2 means 28 times the channel's usual), outlier_score (0 to 100 on one fixed scale: nothing else a run found moves it, so finds from different runs rank together), outlier_tier, channel_size, likes_per_1k, posted_at, duration_s, and the opening: intro (the first minute as it was said: lines of n, t in seconds, text) and intro_text, always whole; and inside it the hook (verbatim: the lines the analysis marks as the hook, ending on a sentence end, at most 25 seconds and 60 words, with hook_words, hook_start_s and hook_end_s, a sponsor read or greeting at the front left out; hook_seconds is hook_end_s). auto_captions says the opening has almost no punctuation. about_subject is yes or partly: a video the model judges not to be about the subject is dropped. The analysis: hook_type (the same list as find_hooks), mechanism (why it holds, quoting the opening word for word), promise, open_loop, title_link (how the first lines pay off the title), beats (the opening in parts: from, to, beat, does), opens_with (cold_open, greeting, teaser, question, sponsor), format (the kind of video), angle, template (the hook as a fill-in structure), steal_it and audience. When the topic asks for a kind of opening ("question hooks", "storytime"), style_match says whether each find is that kind and the matches come first. analysed is false when the model could not analyse an opening: the opening is still real, its analysis fields are null. The run's report.patterns lists the opening types at least two finds share; report.shape says how the openings are built, counted from the finds (hook_seconds, how long the hook runs, and hook_words as medians, beats with how many openings use each and the second it usually starts_at, and the sequence of beats most of them share); and report.openers holds up to `openers` (3 by default, 0 for none) openings WRITTEN for your topic from those structures (hook, then, hook_type, based_on). report.openers_label is always "Written by Hook Detector from the structure of these real openings": show it with them, never present one as a real video's opening. report.landscape is the subject at a glance, counted from the videos the run held against their own channel (videos, channels, outliers and their share, breakouts, small_channel_outliers, recent_outliers). The run's hooks and bonus are always empty. A link instead of a subject: when topic is a channel's YouTube address (https://www.youtube.com/@name, or just @name) the run returns that channel's OWN outliers, its recent long-form uploads that beat its usual (one provider call, no search); when it is a long-form video's address the run returns that one video, whatever its multiple (requested is 1). options.link says "channel" or "video". No openings are written for a link (use remix_find on a find to write for your niche). A Short's address is refused with 422. Arguments: topic 3 to 500 characters; count 1 to 30 (default 8); language and country optional; posted_within_days 30, 90, 365 or 730 to narrow the 2023 floor further; channel_size "small", "mediu

• 2026-10-09get_runchangeddescription
  before

  A research run: its status, progress, charge and every hook it produced. 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. 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 5 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. 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.

  after · 88% of words in common

  A research run: its status, progress, charge and every hook it produced. 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 5 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. 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.

Showing the latest 10. Full history: list_changes · trend: quality JSON.

Checks run on what our credential-free, read-only probes observe; tools are never called and no code audit is performed. How it is computed.