A TikTok API for research, not posting

Resolves the job handle returned by generate_script into the finished script. Status is processing, completed or failed, and the response carries a retry_after_seconds hint for how long to wait between attempts while it is still processing.

Resolves the job handle returned by search_viral_trends into the finished results. Status is processing, completed or failed, and the response carries a retry_after_seconds hint for how long to wait between attempts. A search already in flight is resolved here; starting another for the same hashtag spends a second viral search from the monthly allowance. Off-topic results (judged by the relevance check) are left out by default and counted in hidden_count; pass include_hidden to get them. While the relevance check is still running the status stays processing and relevance_pending is true; poll again until it is false.

Search analyzed videos and slideshows in this workspace by username, view count, date range, or format ('video' or 'slideshow'). Each row carries platform ('tiktok' or 'youtube') and post_format ('photo' carousel, 'slideshow' template, 'video', or null for a video).

Full AI analysis for one video or slideshow. A video returns hook, timing, scenes and transcript; a slideshow (schema_version carousel_v1) returns cover, slide-by-slide breakdown, narrative, aesthetic, audio, swipe and save drivers, and scores.

Find videos or slideshows similar to a given one using vector search. Each row carries post_format.

List videos currently breaking out among tracked creators. Pass username to see one creator's breakouts.

Browse available niches and their metadata, including catalog_video_count (an approximate count of the videos the niche's catalogue holds, a cached counter updated by the nightly refresh). The workspace's own custom niches come first, then the global catalogue. Each niche has a status: 'active', or 'stopped' (no longer refreshing, but its videos are still there to read). auto_analyse_effective says how its videos get analysed automatically: a global niche ('winners', auto_analyse_shared true) has each refresh's top 10 analysed by fypnow for everyone, free; a custom niche runs 'off', 'winners' or 'all' into this workspace, one catalog slot per video (auto_analyse_mode is the stored choice, null = plan default), and auto_analyse_paused_reason 'catalog_full' means it stopped because the catalog is full (upgrade or free slots). Paginated: when meta.has_more is true, request the next page. Returns niches only, not videos, and carries no per-video AI analysis; that lives behind analyze_tiktok_video. Per-niche numbers (typical views, breakouts, top creators, hashtags) come from get_niche_stats.

Suggest search keywords for a niche idea from what the catalogue already holds: the hashtags that co-occur with the topic (topic, up to 60 characters) in videos from the last 30 days across every niche you can see, ranked by distinct videos, with generic tags such as fyp and viral left out. Each keyword carries videos (how many videos use it) and source: hashtag, or topic when nothing in your niches mentions the topic yet (the topic itself then comes back with videos 0 and a note). matched_global_niche names an existing global niche that already covers the topic, if one does. limit is 1-20 (default 6). Keywords are sized for create_niche (1-3 short phrases). No AI call and no TikTok request is made.

Top videos in one niche, ranked by multiplier: the video's views divided by its creator's follower count (subscribers for YouTube). As an MCP tool it takes the niche's name (e.g. 'forex'; matched case-insensitively on name, then slug, then singular/plural ('protein noodle' finds 'Protein Noodles'), then the niche's keywords, preferring your own niche over a global one) or a niche id from browse_niche_catalog: pass the name directly rather than browsing first. Your stopped niches still answer; meta.niche gives the niche's status ('active' or 'stopped') and last_refreshed_at, so say when a stopped niche last refreshed. Over REST the id is in the path. Returns catalogue stats — views, likes, author, multiplier, platform — not per-video AI analysis. Niches mix TikToks and YouTube Shorts; platform is 'tiktok' or 'youtube'. A hook and scene teardown of a TikTok or a Short comes from analyze_tiktok_video, which takes its video_url. Rows carry no hook data; the top hooks in a niche come from get_niche_hooks. Each row carries post_format; the format input ('video' or 'slideshow') narrows the list to one. Each row also carries content_format (talking_head, voiceover_broll, slideshow, text_on_screen, skit, tutorial, pov, vlog, compilation or other, or null) and content_format_source: 'analysis' when the video has had a full analysis, 'estimated' when it is a guess from the caption, hashtags and cover only (the video itself was not watched). Estimates appear only for formats we have checked; unlabelled videos have null. The content_format input narrows the list to one, within the niche's top 1,000 videos.

The top hooks in one niche: hook types from the niche's most viral videos (its top 100 catalogue rows by multiplier) that this workspace has analysed. Takes the niche's name (matched like get_niche_videos) or a niche id. Hooks come from videos this workspace has analysed with analyze_tiktok_video and, for a global niche, from the top videos fypnow analyses for everyone after each refresh (examples carry shared: true); catalogue rows carry no hook data, and other workspaces' analyses are never used. Returns hooks (per hook_type: videos, avg_multiplier, up to 3 examples with hook_text (best first) and up to 3 reusable fill-in templates [{template, count, example_video_id}], ordered by how many top videos use the hook), analysed_count, catalog_considered, and next_to_analyse: the next most viral unanalysed videos (slideshows left out, since their analysis has no hook), each with a ready video_url for analyze_tiktok_video. limit sizes next_to_analyse (default 10, max 25). When few or none are analysed, the answer is to offer analysing next_to_analyse; each analysis costs one catalog slot, and nothing is analysed without the user agreeing. meta.niche gives the niche and its status.

The top breakout videos across every niche you can see (the global catalogue plus your own niches) that entered the catalogue in the last N hours (hours, 6-168, default 48). Optional niche (id or name) narrows it to one niche, platform to 'tiktok' or 'youtube'. Ranked by multiplier (views / followers) by default, or order_by 'weighted' for ln(views / followers) x ln(followers), which favours big wins on larger accounts. Each row carries the niche, author, a ready url for analyze_tiktok_video, views, followers, multiplier, weighted_score, posted_at and first_seen_at. limit is 1-50 (default 20); the list is not paged. An empty window returns an empty list with meta.hours and meta.since. Catalogue stats only, not per-video analysis.

The hashtags gaining the most ground across every niche you can see (the global catalogue plus your own niches). Compares the distinct creators posting videos that entered the catalogue in the last N days (days, 1-30, default 7) with the N days before: each tag carries creators, prev_creators, growth ((creators - prev_creators) / max(prev_creators, 1)), videos, prev_videos, median_multiplier and top_video_id. Tags used by fewer than 3 creators in the window are left out, as are generic platform tags such as fyp and viral. Optional niche (id or name) narrows it to one niche. limit is 1-50 (default 20); the list is not paged. Catalogue stats only, not per-video analysis.

One hashtag in the catalogue (a leading # and capital letters are ignored): a daily series of how many videos used it and their median multiplier over the last N days (days, 7-90, default 30), total_videos, and the top 5 videos with a ready url for analyze_tiktok_video. Optional niche (id or name) narrows it to one niche. A tag with no videos returns an empty series, not an error. Catalogue stats only, not per-video analysis.

Search the hooks of analysed videos across every niche you can see (the global catalogue plus your own niches): your own analyses and fypnow's shared ones, best multiplier first. Optional query is a 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 or visual_spectacle, niche (id or name) narrows it to one niche. Each row has the hook text, a reusable fill-in hook_template (null for older analyses), the niche, author, a ready url for analyze_tiktok_video, views and multiplier. limit is 1-50 (default 20); the list is not paged. Videos nobody has analysed yet are not searched.

Trends several creators are posting about right now, across every niche you can see (the global catalogue plus your own niches): a news event, a release, a match or a challenge, detected daily from the catalogue. Each trend has a status (new, rising, peaking, fading or ended) and status_since, the niche, videos, creators, best_multiplier (views / followers), first_seen and last_seen (dates of its first and latest video), detected_at, a daily series (videos and new creators per day, with that day's status), 3 to 6 example videos with a ready url for analyze_tiktok_video, suggested keywords for a niche agent, its most shared hashtag, and also_in (other niches with the same videos). Optional niche (id or name), status (comma list or open, default open: new, rising, peaking and fading) and days (1-60, default 14). limit is 1-50 (default 20; a value outside that range is clamped to it, not rejected); the list is not paged. meta carries as_of (the date of the latest daily check) and backfill_complete. Trend names are generated from captions. Catalogue stats only, not per-video analysis.

One trend from get_trends by id, with the same fields plus members: every visible video in it (up to 50, best multiplier first, each with a ready url for analyze_tiktok_video). The multiplier is views / followers. An unknown id, or a trend outside the niches you can see, is a 404.

Stats for one niche from its nightly snapshot: typical post views, breakout posts (3x or more the creator's followers), active creators and views on this week's top posts, each next to the snapshot from a week earlier; top and rising creators, sounds in use, top hashtags, posting times, the top 3 posts this week, posts and breakouts per posting day, and the daily snapshot series. Takes a niche id from browse_niche_catalog. The numbers describe the top posts the nightly crawl keeps per niche (about 50 a night, about 100 for custom niches), not all of TikTok. latest is null until the first nightly snapshot, and week-over-week comparisons need a week of snapshots. format_mix counts the niche's videos posted in the window by content_format [{content_format, breakouts, all, source}] (breakouts = 3x or more the creator's followers), with source 'analysis', 'estimated' (a caption-and-cover guess, shown only for formats we have checked) or 'mixed'; format_mix_unlabelled counts videos with no usable format.

List tracked creators in this workspace, with their ids.

Profile, follower history, winning patterns, posting cadence and hit rate for one creator.

List generated scripts in this workspace.

Fetch one generated script by id.

List videos saved to the workspace library.

Grade the workspace own account against its niche benchmarks.

Current plan allowances and consumption. Free and unmetered.