Trending videos, hashtags and hooks

These reads look across the whole catalogue instead of one niche: the global niches plus your own Viral Content Agents. They return catalogue statistics only. For a hook and scene breakdown of a single video, pass its url to analyze_tiktok_video. All of them are read tools, so they work with a read-only key and draw down no plan quota.

These tools rank single videos and hashtags. A trend is a different thing: a group of creators in one niche posting about the same specific thing within a few days, detected automatically once a day, with a status (new, rising, peaking, fading or ended). Read those with get_trends and get_trend; see Trends.

get_trending_videos

GET /v1/trending/videos returns the top videos that entered the catalogue in the last N hours. Ranking is by multiplier unless you ask for order_by=weighted.

• hours: look-back window, 6 to 168, default 48. It counts from when the video entered the catalogue, not from when it was posted.
• niche: a niche id or name, to narrow it to one niche.
• platform: tiktok or youtube.
• order_by: multiplier (default) or weighted.
• limit: 1 to 50, default 20. The list is not paged.

Example request and response (values are illustrative):

GET /v1/trending/videos?hours=72&order_by=weighted&limit=2

{
  "data": [
    {
      "video_id": "7600000000000000001",
      "platform": "tiktok",
      "niche": { "id": "6b1f0c2e-...", "slug": "fitness", "name": "Fitness" },
      "author_username": "examplecreator",
      "url": "https://www.tiktok.com/@examplecreator/video/7600000000000000001",
      "thumbnail_url": "https://...",
      "views": 1500000,
      "followers": 60000,
      "multiplier": 25,
      "weighted_score": 35.41,
      "posted_at": "2026-10-21T14:03:00+00:00",
      "first_seen_at": "2026-10-22T02:10:00+00:00"
    },
    {
      "video_id": "7600000000000000002",
      "platform": "tiktok",
      "niche": { "id": "9d4a77b0-...", "slug": "food", "name": "Food" },
      "author_username": "anothercreator",
      "url": "https://www.tiktok.com/@anothercreator/video/7600000000000000002",
      "thumbnail_url": "https://...",
      "views": 300000,
      "followers": 12000,
      "multiplier": 25,
      "weighted_score": 30.23,
      "posted_at": "2026-10-22T09:30:00+00:00",
      "first_seen_at": "2026-10-22T20:45:00+00:00"
    }
  ],
  "meta": {
    "hours": 72,
    "since": "2026-10-20T06:00:00+00:00",
    "order_by": "weighted",
    "niche": null,
    "page": 1, "limit": 2, "total": 2, "total_pages": 1, "has_more": false
  }
}

An empty window returns an empty list with meta.hours and meta.since, not an error. A video that sits in two niches appears once, under the niche where its multiplier is higher.

get_trending_hashtags

GET /v1/trending/hashtags compares the distinct creators using each hashtag in the last N days with the N days before. A tag only counts when at least 3 different creators used it in the window, so one busy account cannot make a trend. Generic platform tags such as fyp and viral are left out.

• days: 1 to 30, default 7.
• niche: a niche id or name.
• limit: 1 to 50, default 20. Not paged.

Each tag carries creators and prev_creators, growth = (creators − prev_creators) ÷ max(prev_creators, 1), videos and prev_videos, median_multiplier and top_video_id.

GET /v1/trending/hashtags?days=7&limit=1

{
  "data": [
    {
      "tag": "mealprep",
      "videos": 14,
      "prev_videos": 5,
      "creators": 9,
      "prev_creators": 3,
      "growth": 2,
      "median_multiplier": 6.4,
      "top_video_id": "7600000000000000003"
    }
  ],
  "meta": { "days": 7, "niche": null, "page": 1, "limit": 1, "total": 1, "total_pages": 1, "has_more": false }
}

lookup_hashtag

GET /v1/hashtags/{tag} answers one hashtag. A leading # and capital letters are ignored. You get a daily series of how many videos used it and their median multiplier, total_videos for the window, and the top 5 videos, each with a ready url. A tag with no videos returns an empty series, not an error.

• tag: required, up to 100 characters, no spaces.
• days: 7 to 90, default 30.
• niche: a niche id or name.

GET /v1/hashtags/mealprep?days=30

{
  "data": {
    "tag": "mealprep",
    "days": 30,
    "total_videos": 41,
    "niche": null,
    "series": [
      { "day": "2026-10-21", "videos": 3, "median_multiplier": 5.8 },
      { "day": "2026-10-22", "videos": 2, "median_multiplier": 7.1 }
    ],
    "top_videos": [
      {
        "video_id": "7600000000000000003",
        "platform": "tiktok",
        "niche": { "id": "9d4a77b0-...", "slug": "food", "name": "Food" },
        "author_username": "examplecreator",
        "url": "https://www.tiktok.com/@examplecreator/video/7600000000000000003",
        "thumbnail_url": "https://...",
        "views": 820000,
        "followers": 41000,
        "multiplier": 20,
        "posted_at": "2026-10-19T11:00:00+00:00",
        "first_seen_at": "2026-10-19T23:30:00+00:00"
      }
    ]
  }
}

search_hooks

GET /v1/hooks searches the hooks of videos that have already been analysed: your own analyses and fypnow's shared ones, best multiplier first. Videos nobody has analysed are not searched, so an empty result can mean "not analysed yet", not "no such hook".

• query: case-insensitive text match on the hook, up to 80 characters.
• hook_type: one of question, bold_claim, curiosity_gap, shock, relatable, tutorial_promise, story_opener, visual_spectacle.
• niche: a niche id or name.
• limit: 1 to 50, default 20. Not paged.

Each row has the hook text, a reusable fill-in hook_template (null for older analyses), the niche, author, a ready url, views and multiplier.

GET /v1/hooks?hook_type=question&limit=1

{
  "data": [
    {
      "video_id": "7600000000000000004",
      "url": "https://www.tiktok.com/@examplecreator/video/7600000000000000004",
      "hook_type": "question",
      "hook_text": "Why does nobody tell you this about meal prep?",
      "hook_template": "Why does nobody tell you this about [topic]?",
      "niche": { "id": "9d4a77b0-...", "slug": "food", "name": "Food" },
      "multiplier": 18.5,
      "views": 740000,
      "author_username": "examplecreator",
      "platform": "tiktok"
    }
  ],
  "meta": { "query": null, "hook_type": "question", "niche": null, "page": 1, "limit": 1, "total": 1, "total_pages": 1, "has_more": false }
}

Hook templates for one niche

get_niche_hooks (GET /v1/niches/{id}/hooks) also returns templates inside each hook type: up to 3 reusable fill-in templates, each as {template, count, example_video_id}, most common first. count is how many of the niche's analysed top videos use that template.