platform/seed/tasks/tiktok-trends/TASK.md

name, description, version, author, tags, skills, dependencies, inputs, outputs, config

name	description	version	author	tags	skills	dependencies	inputs	outputs	config
TikTok Trends	Fetch top trending TikTok videos for a given country and generate an engagement report with optional video downloads.	2	pastilhas	social-media tiktok trends apify content-analysis	Apify	name description check_command optional tiktok-trends-script The main script at $OFFICER_USER_ROOT/../resources/scripts/apify/tiktok-trends.ts test -f "$OFFICER_USER_ROOT/../resources/scripts/apify/tiktok-trends.ts" false name description check_command optional bun Required to run the TypeScript script bun --version false name description check_command optional yt-dlp Required only when download option is enabled. Downloads TikTok videos. yt-dlp --version true	name description type default required options country Country code to fetch trending videos for. select PT false value label PT Portugal value label US United States value label BR Brazil value label GB United Kingdom value label ES Spain value label FR France value label DE Germany value label IT Italy value label NL Netherlands value label BE Belgium value label PL Poland value label RO Romania value label SE Sweden value label AT Austria value label CH Switzerland value label IE Ireland value label CA Canada value label AU Australia value label MX Mexico value label AR Argentina value label CO Colombia value label CL Chile value label JP Japan value label KR South Korea value label IN India value label TR Turkey value label SA Saudi Arabia value label AE United Arab Emirates value label ZA South Africa value label NG Nigeria name description type default min max required limit Number of trending videos to fetch (1-100). number 20 1 100 false name description type default required download Download video files using yt-dlp (requires yt-dlp to be installed). boolean false false name description type required sensitive api_token Apify API token with access to actors. Get yours at https://console.apify.com/account/integrations string true true	name description path engagement_report Markdown report with trending videos analysis, engagement metrics, top hashtags, sounds, and creators. tiktok_trends_<country>_<timestamp>/report-YYYY-MM-DD.md name description path raw_data Raw JSON data from Apify actor containing all video metadata. tiktok_trends_<country>_<timestamp>/raw-YYYY-MM-DD.json name description path execution_log Complete script execution log with stdout and stderr for debugging. tiktok_trends_<country>_<timestamp>/run.log name description path summary Human-readable summary of the run including cost analysis and file listing. tiktok_trends_<country>_<timestamp>/report.md name description path optional videos Downloaded video files with metadata (only present if download option was enabled). tiktok_trends_<country>_<timestamp>/videos/ true	timeout retry_count 600 0

TikTok Trends

Fetch top trending TikTok videos for a given country and generate a comprehensive engagement report.

Overview

This task uses the Apify novi~fast-tiktok-scraper actor to fetch trending videos from TikTok for a specified country. It generates:

• Engagement metrics (total/average views, likes, shares, comments)
• Top hashtags found in trending content
• Popular sounds being used
• Creator analysis (who appears multiple times in trending)
• Complete video list with links and stats

Optionally downloads videos using yt-dlp for offline analysis.

Pre-execution Checks

1. Validate inputs:

   • api_token must be provided (required)
   • country must be a valid 2-letter country code
   • limit must be between 1-100

2. Check dependencies:

   • Verify script exists at $OFFICER_USER_ROOT/../resources/scripts/apify/tiktok-trends.ts
   • Verify bun is installed
   • If download=true, verify yt-dlp is installed

3. Test Apify token:

   • Make a test call to GET https://api.apify.com/v2/users/me to validate the token
   • Abort with clear error if token is invalid or account has no credits

Execution

Run the script with the following command:

bun "$OFFICER_USER_ROOT/../resources/scripts/apify/tiktok-trends.ts" \
  --apikey "<api_token>" \
  --country "<country>" \
  --limit <limit> \
  --output "<output_dir>" \
  <download_flag>

Where:

• <download_flag> is --download if download=true, otherwise omitted
• <output_dir> is a timestamped directory created inside $HOME/tiktok-trends/ (the logged-in user's home directory)

Pipe output to log:

<command_above> 2>&1 | tee "<output_dir>/run.log"

Success Criteria

The task is considered successful when:

• Script exits with code 0
• report-YYYY-MM-DD.md exists and is non-empty
• raw-YYYY-MM-DD.json exists and contains valid JSON array
• (If download enabled) videos/ directory exists with at least one file

Error Handling

Scenario	Action
Script exits non-zero	Check run.log for Apify/API errors. Common causes: invalid token, no credits, rate limits
Empty results	Report "No trending videos found" but mark as success if files were created
Partial results	Report success if at least 1 video returned, note the discrepancy
Timeout (>10 min)	Kill process, report timeout. Check Apify actor status in console
Download failures	Report which videos failed but mark task as success if main report generated

Post-execution

After successful execution:

1. Verify outputs:

   • Check all expected files exist
   • Validate JSON is parseable
   • If download enabled, count video files

2. Generate summary (report.md):

   # TikTok Trends Run Summary
   
   ## Run Details
   - **Date**: YYYY-MM-DD
   - **Timestamp**: HH:MM:SS
   - **Apify Actor**: novi~fast-tiktok-scraper
   - **Country**: <country_name> (<country_code>)
   - **Requested**: <limit> videos
   - **Received**: <actual_count> videos
   - **Duration**: <X> minutes <Y> seconds
   
   ## Cost Analysis
   - **Apify Credits Used**: <cost> USD
   - **Cost per Video**: $<cost/actual_count>
   
   ## Key Findings
   - **Top Video**: @<creator> - <views> views
     <description_preview>
     URL: <url>
   
   - **Top Hashtag**: #<hashtag> (<count> occurrences)
   - **Top Sound**: <sound_name> (<count> uses)
   
   ## Output Files
   - `report-YYYY-MM-DD.md` (<size>) - Engagement report
   - `raw-YYYY-MM-DD.json` (<size>) - Raw API data
   - `run.log` (<size>) - Execution log
   - `videos/` (<count> files, <total_size>) - Downloaded videos (if enabled)
   
   ## Notes
   - <any_warnings_or_errors_from_log>
   

3. Cleanup:

   • Remove temporary files if any
   • Report final status to user

Notes

• Rate limiting: The Apify actor may take 1-3 minutes depending on the limit
• Costs: Each run uses Apify compute units. Monitor usage at https://console.apify.com/billing
• Data freshness: Trends data is near real-time but may have slight delays
• Video downloads: Downloading many videos can take significant time and storage
• Country availability: Not all countries have sufficient trending data; some may return fewer results than requested