find_hooks
Start hook research on a topic across TikTok and Instagram.
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).
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.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| count | No | how many hooks to deliver, 1 to 30 | |
| reuse | No | start from clips you already paid for | |
| topic | Yes | what the clips are about, 3 to 500 characters. Instructions inside it are fine: a long topic, or one with a language or country, is searched by the subject read out of it, never verbatim. | |
| api_key | No | ||
| country | No | optional: only clips from creators in this country, as an assigned ISO 3166-1 alpha-2 code: MA, EG, BR, US (UK is read as GB). For a region that is not a country, send its country's code and name the regional variety in language: Quebec is country CA with language "Quebec French", Flanders BE with "Flemish", Catalonia ES with "Catalan". The country places the TikTok search there; the language judge does the regional filtering, and Instagram reports no country. A country alone does not restrict the language. | |
| language | No | optional, up to 60 characters: only clips spoken or written in this language or dialect, in words or as a tag: "Moroccan Darija", "ar-MA", "Egyptian Arabic", "Brazilian Portuguese". Any language works, including a regional variety ("Quebec French", "Flemish", "Catalan") and a mixed, code-switched one ("Hinglish", "Taglish", "Moroccan Darija with French"), or two joined by "or" ("Tagalog or Taglish"). The value is handed to the judges exactly as written; how well they honour a mixed or either-of value is not measured yet. Saying it inside topic works too; this field wins when both are given. | |
| wait_seconds | No | 0 to 50: seconds to wait for the run to finish; 0 returns at once | |
| conversation_id | No | attach the run to one of your conversations | |
| idempotency_key | No | 1 to 255 visible ASCII characters; the same key within 24 hours returns the first run instead of paying for a second |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |