trends

Invocation#

echo-cli trends sounds --runs <n>
echo-cli trends hashtags --runs <n> [--industry <industry>]
echo-cli trends watches --product <id>
echo-cli trends watch --product <id> --term <phrase-or-hashtag> --climb <places> --notify <user-id> --by <name>
echo-cli trends unwatch --id <watch-id>
echo-cli trends check --kind sounds|hashtags [--run <instant>]
echo-cli trends formats
echo-cli trends format --format <name> --hashtags <tag,tag…> --by <name>
echo-cli trends unformat --format <name>

Inputs and output#

sounds and hashtags write kind, runs (the newest run times read, newest first) and items: each sound or hashtag of the latest run in rank order — key (the sound id or the hashtag), label, artist (sounds), industry (hashtags) and ranks, one per run read with run_at and rank, null where that run did not list it. watches writes the product's watches — id, product_id, term (lower case), climb, notify_user, watched_by, watched_at — each with alerts: kind, item_key, label, run_at, rank, previous_run_at and previous_rank (null when the item entered the ranking), pending_action_id and raised_at, newest first. watch and unwatch write the watch; check writes the alerts the run raised, now or before.

State effect#

Calls Echo Web's authenticated /api/analytics/trends (watches: /api/analytics/trends/watches) with ECHO_INTERNAL_BEARER at ECHO_WEB_BASE_URL; the Trends across runs and Trend alerts sections of the trending page and of Echo Desktop's GEO screen call the same, and echo-mcp reads it as echo_trends and keeps watches with echo_trend_watches, echo_trend_watch, echo_trend_unwatch and echo_trend_watches_check. Every Creative Center scrape run (/api/cron/scrape-creative-center, through TokChart) keeps its sounds and hashtags as they ranked in trend_ranks, beside the latest reading in tiktok_trending_sounds and tiktok_trending_hashtags, so history starts with the first run after trend_ranks exists. --industry keeps the hashtags the source files under that industry; sounds carry none. Reading stores nothing. Each run is checked against every product's watches as it is kept: an item whose label or key holds a watched term (case aside) and that entered the ranking, or climbed at least the watch's --climb places since the run before, raises one pending action (type trend_rising, naming the item, both ranks and both runs) for the watch's user, kept in trend_alerts so the same rise in the same run never alerts twice; check runs the same over the newest run of a kind, or the one --run names.

Refusals#

• A wrong invocation is refused before anything is sent: "trends takes sounds …; hashtags …; got <word>", "trends <verb> does not take <flag>; it takes …", "<flag> needs a value" and "trends <verb> needs --runs".
• Echo Web answers a bad request with "runs must be a positive whole number: how many of the newest scrape runs to read; got <value>" or "sounds carry no industry, so they cannot be narrowed to <industry>". The command prints Echo Web's sentence and exits 1.
• watch is refused with "--climb must be a number; got <text>" before anything is sent, and by Echo Web with "term is required: …", "climb must be a positive whole number: the places an item must climb between two runs to count as rising; got <value>", "notify_user is required: …", "no product has id <id>; …" or "product <id> already watches \"<term>\" as <watch id>, since <time>"; unwatch with "no trend watch has id <id>"; check with "kind must be one of sounds, hashtags; got <value>", "run_at, when given, is the instant of a stored run; got <value>", "no <kind> run is stored yet; the Creative Center scrape stores one" or "no <kind> run was stored at <instant>". A pending action or alert that cannot be stored is the error naming the item and the watch.
• formats writes every declared viral format by name: format, hashtags (without #), declared_by and declared_at; format declares one, or replaces the hashtags of one declared before, and writes it; unformat removes one and writes it, its stored references staying. The daily /api/cron/scrape-viral scrapes the format ?format= names, or else the declared formats in name order, one each UTC day: each hashtag's TikTok videos with at least ECHO_VIRAL_REFERENCE_MIN_VIEWS views and a caption are stored once in viral_references with their counts and interactions per view, then summarized by the model; it answers { format, hashtags, scraped, saved, classified, failures }, every hashtag that could not be scraped, video that could not be stored and summary that failed named with why, and records the run in the automation audit trail (scrape viral references: what was saved and summarized, failed when nothing was). The Viral formats sections of the trending page and of Echo Desktop's GEO screen declare and remove the same. Usage errors: "trends format needs <flag>" for each of --format, --hashtags and --by, and "trends unformat needs --format". Echo Web answers a bad request with "format is required: …", "hashtags is required: the TikTok hashtags, without #, that discover what is viral in the format now" or "declared_by is required: …", and not found with "no viral format is declared as <name>; echo-cli trends formats lists them"; the scrape answers not found with "no viral format is declared, so there is nothing to scrape; echo-cli trends format declares one" or "no viral format is declared as <name>; echo-cli trends format declares one".