Appearance
Trending media
Every client has a Trending tab (owner and manager): the videos working right now in the client's niche, ranked by how fast they are gaining views, with AI help for what to search and what to shoot. Everything is read from public pages with no login. The idea and the source list come from Reroot's trending scraper, rebuilt for Cloudflare Workers.
What it reads, and what it does not
| Platform | How | Notes |
|---|---|---|
| YouTube | Results page for a keyword (ytInitialData in plain HTML), twice: all time and "this week". The freshest and fastest videos then get their watch page read for the exact date, likes, comments and views. | Works over plain HTTP. Shorts are included. |
Discovery through the Brave Search API when BRAVE_API_KEY is set, otherwise a scraped DuckDuckGo results page. Each reel's public embed page then states its play count, owner, caption and date. | The scraped page can be refused from a datacenter address; the run log says so. | |
| TikTok | Followed creators only: the public embed page (recent videos with play counts, followers) plus oEmbed for titles and thumbnails. | TikTok's keyword and hashtag pages show a captcha to automated browsers. We do not bypass it. |
| TikTok hashtag (experimental) | One attempt per run through Cloudflare Browser Rendering. | A captcha is detected and reported, never worked around. Usually reads nothing. |
| Followed pages: the public page lists recent videos, each video's link preview states its views. | Per page, not by keyword. |
For keyword trends on TikTok the supported routes are a data provider or TikTok's Research API; neither is wired in.
How a refresh works
- Searches and accounts. A client keeps saved searches and followed accounts. If it has none, the first run takes them from the research brief (category, area, products, themes, trends; competitors and creators with their handles) so the tab works the moment research exists. Staff can edit both, and Suggest searches asks the model for more, each with a reason tied to the brief (it falls back to brief-derived suggestions when no model is configured).
- Read.
trending.runcreates a run and queues thetrending.runjob. The job reads up to 12 searches and 60 followed accounts per run. Accounts are read TikTok first, then Instagram (four at a time), then Facebook and YouTube, least recently read first, so every account comes round over successive runs. Account reads stop after a 4-minute slice, and the run log says how many were read (Read N of M followed accounts (time budget)). One source failing never fails the run; every source writes one line in the run log, including the blocked and empty ones. - Rank. Only videos with a known publish date count. A video with no date after its watch-page read is dropped, and the run log says how many. Searched videos must be from the last 45 days; when fewer than 25 survive, videos from the last 90 days are added below them, and the run log says so. A searched video also needs at least 2,000 views and at least 2 views an hour since it was published, so slow old videos drop out. Relevance is judged by the model against the client's own context (name, category, area, brief, offerings, audience, what the business sells): a video is kept when it is a useful reference for this business, the same niche or an adjacent format it could copy, and dropped when it only mentions the place or the topic word in passing, such as a travel vlog or a wedding. Posts that show menu items, drinks, the space, staff or customers count as copyable. The model judges up to 240 search results per run, in batches of 24 with three batches in flight. The pool is spread round-robin across queries (dated first, then most viewed, inside each query) so one broad query cannot fill it, and a video is kept at a score of 0.6 or more. Judging starts no new batch after 8 minutes and the run log says so. Content from the client's own market (its area) scores slightly higher than equal content from elsewhere; a non-local video with a format the business could copy still counts. Word matching is only the fallback, used when no model is configured or when a reply leaves a video without a verdict. YouTube rows with no date are looked up on their watch page (up to 200 per run, one at a time with a short pause, most relevant first). What is left is ranked by velocity: views per hour since publish, at most 150 per client. Followed creators' videos are judged with a lower bar and kept at any size, since you follow them on purpose: kept at relevance 0.4 or more when the video is a clear outlier (1.0 or more of its account's median views) or 0.7 or more otherwise. Facebook gives no date, so a followed Facebook page's videos are kept with no age shown. Counts are the platform's own; nothing is estimated.
- Keep. Items are stored once per client and video and refreshed by later runs. A dismissed video stays dismissed; saved ones stay on top.
- Stay fresh. The
trending.refreshcron sweep refreshes one stale client per tick (oldest first, older than 24 hours).
AI lookups
- Suggest searches (per client): grounded in the brief; saved only when you add them.
- Find accounts (per client): the model runs two passes with web search. The first names local competitors and niche creators in the client's market: 15 Instagram and 15 TikTok accounts, plus up to 5 on Facebook or YouTube. The second names best-in-class accounts in the niche worldwide, saved with a
Global reference:note so their formats can be copied: 10 Instagram and 10 TikTok, plus up to 5 YouTube. Every handle is then read live, and only accounts with at least three videos are saved as followed accounts (sourceai, with the reason as the note). Up to 40 are saved per call, and a client follows at most 60. Invented or empty accounts are rejected and listed in the run log. A run asks for accounts only while the client follows fewer than 12, and at most once per 24 hours. The manual action returns an error when no model is configured. - Why it works (per video): the model reads the video's title, caption, numbers and age with the client's brief and returns why it works, the hook, the format, a 1 to 5 fit, and a shoot idea (title, hook, shots). It is told not to invent numbers. Needs a configured model (
ANTHROPIC_API_KEYin production, the Claude bridge in development); without one the button says so.
Thumbnails
After a run, up to 30 kept videos without an image get one. The platform's own image is used when it can be fetched; otherwise the public embed page is screenshotted (needs the Browser Rendering binding; without it those videos show a placeholder). Images are stored privately and served only to owner and manager; anyone else gets a 404.
Quality signals
- Outlier score: for each followed account, a video's views divided by that account's median views in this run. Needs at least 4 of its videos with views; accounts with fewer get no score. A followed account's video adds
25 × min(outlier, 8) × relevanceto its trend score, so a standout video rises above its routine ones. - Followed accounts: kept at relevance 0.4 or more, and only when they are an outlier (1.0 or more of their median) or the relevance is 0.7 or more. Ads, giveaways, partnership posts and announcements score low, so they drop out.
- Searched videos: kept at relevance 0.6 or more.
- Mention snowball: a handle that at least 2 distinct kept videos scoring 0.7 or more mention (in their title, caption or author text), and that is not already followed, is verified live (at least 3 videos) and followed on the same platform, source "AI", with the note
Mentioned by followed accounts. At most 10 per run and 60 followed per client. The run note says how many were added. - Limits per run: up to 12 enabled queries, 600 candidate videos, 200 watch-page date lookups, a 25-video recent target (videos from 45 to 90 days fill in below it), and an overview of 200 items.
- Platform quotas: the list keeps at most 60 Instagram, 60 TikTok, 40 YouTube and 10 Facebook videos, by trend score. The run note reads
Kept: Instagram X, TikTok Y, YouTube Z, Facebook W. - The list: a run that finds at least 30 videos replaces the unsaved list. Videos from older runs that it did not keep are removed, and so are unsaved videos from accounts it stopped following. Saved and dismissed videos are never removed. A run that finds fewer than 30 removes nothing, and the run log says how many were cleaned up.
Configuration
| Name | Required | Purpose |
|---|---|---|
BRAVE_API_KEY | no | Instagram discovery through the official Brave Search API instead of a scraped results page. |
| Browser Rendering binding | no | Already bound for research; used for the experimental TikTok hashtag attempt. |
| Research model | no | Suggestions beyond the brief, and per-video analysis. |
Code map
- Contract:
packages/domain/src/trending.ts,packages/db/src/schema/trending.ts,packages/api/src/trending/types.ts. - Readers and ranking:
packages/api/src/trending/{youtube,instagram,tiktok,facebook,rank,sources}.ts. - Service, AI, job:
packages/api/src/trending/service.ts,packages/api/src/jobs.ts(trending.run, sweeptrending.refresh). - UI:
apps/web/src/components/owner/clients/trending-tab.tsx.
Responsible use
Pages are read the way a visitor's browser or a link preview reads them, at a low rate. A refusal (captcha, 429, login wall) ends that source for the run and is shown in the log. Do not add captcha solving, fingerprint spoofing or logged-in sessions: they break the platforms' terms and the first change on their side breaks them.