Hooklayer
All tools/search_videos2 creditsresearch

What is search_videos?

search_videos is a Hooklayer MCP tool that does keyword search across the live TikTok corpus. Pass a free-text query, optionally narrow by niche / min_views / window / region, and get up to 20 videos ranked by engagement (views + shares*5 + saves*8 + likes*0.5 + comments*2). Each video carries id, description, url, views, likes, shares, saves, comments, duration, hashtags, posted_at, and author — chain any URL straight into viral_remix to draft a fresh script.

Get free API keyTry in playground

Filters that actually filter. Pass a niche ("Beauty & Skincare", "Fitness & Health", etc.) and the route drops any video whose description doesn't contain niche-related tokens. Pass min_views=100000 and the upstream min-views floor enforces it. Pass window=7d / 30d / this-month and the recency cutoff applies BOTH at the ScrapeCreators date bucket AND a defense-in-depth client-side filter so old viral videos don't leak through.

Honest empty-state. If the filters match zero videos, the response carries success: false + a warning + quality.reason explaining what to broaden. No credits are charged when filtered_count = 0. You never silently burn budget on an over-tight filter.

Built for the agentic chain. The natural follow-up is viral_remix on any returned URL — search_videos finds the swipe file, viral_remix turns it into your script. Or pair with score_hook + predict_virality to gate the output before publish.

Inputs & outputs

Endpoint: POST /api/v1/search

Inputs

  • querystringrequired

    Free-text search term (e.g. "morning routine", "iphone case", "passive income").

  • nichestring

    Optional niche filter. Loose names like "fitness" auto-map to canonical "Fitness & Health".

  • min_viewsinteger

    Optional view-count floor (default 0).

  • windowstring

    Recency filter: "24h" | "7d" | "30d" | "this-month".

  • regionstring

    ISO country code (US, GB, BR, PH, JP, etc.). Small-region results may degrade quality.

  • limitinteger

    Max videos to return (1-20, default 12).

Output fields

  • videos

    Array of normalized video objects (id, description, url, views, likes, shares, saves, comments, duration, engagement_score, hashtags, posted_at, author).

  • upstream_count

    Videos returned by upstream before filtering.

  • filtered_count

    Videos returned after filtering + cap.

  • applied

    Echo of the filters actually applied — debug surprising empty results.

  • quality

    level (full | partial | degraded) + reason.

cURL

curl 'https://hooklayer.dev/api/v1/search?query=morning+routine&min_views=100000&window=7d&limit=5' \
  -H "Authorization: Bearer hl_live_..."

Example prompts

Paste any of these into Claude Desktop (with Hooklayer connected) to see the live response.

Find recent winners for a niche product

Use Hooklayer search_videos to find viral TikTok videos about "ceramic non-stick pan" with at least 200K views in the last 30 days. Show me the top 5 ranked by engagement_score with URL + posted_at + view count.

Expected output: Returns 5 videos with URLs you can hand to viral_remix or open manually for inspiration.

Discovery → remix chain

search_videos for "ai tool demo" with min_views=500000 and window=7d. Then for the top result, run viral_remix on the URL and draft a fresh script for an AI productivity app.

Expected output: search_videos returns the swipe file, viral_remix returns the new script. One conversation, two tool calls.

Honest empty-state probe

search_videos for "underwater basket weaving" with min_views=10000000. Expect zero results and a warning.

Expected output: Returns success: false, filtered_count: 0, warning: "no videos matched the filters" — and no credits are charged.

Frequently asked

How is search_videos different from find_viral_template?

find_viral_template is niche-aggregated — pass a niche and get the templates Hooklayer has scored as strong for that niche. search_videos is query-driven — pass any free-text term and get the raw video board for THAT specific query. Use find_viral_template when you want "what generally works in beauty"; use search_videos when you want "what is viral for the keyword serum right now."

How is search_videos different from trend_pulse?

trend_pulse returns trending TOPICS (rising format/hook/style patterns). search_videos returns actual VIDEOS for a known query. trend_pulse answers "what should I post about"; search_videos answers "show me videos doing well on this exact term."

Why does it cost 2 credits?

search_videos hits the live ScrapeCreators TikTok keyword search API + applies filters + ranks by engagement. Each call burns one upstream API credit + 1 credit for our compute. Pricing reflects vendor cost; the honest-empty-state pattern means you never pay when results are zero.

What region defaults if I don't pass one?

Defaults to US. The ScrapeCreators upstream is US-skewed. If you pass region=JP and the corpus has minimal coverage, the response will return zero and the quality.reason will mention the region — surface that verbatim to the user instead of silently failing.

Related tools

Try search_videos in 30 seconds.

50 free credits at signup. No card. Works in Claude Desktop, Cursor, n8n, or any MCP client.

Get API keyInstall for Claude / Cursor / n8n