TikTok Video Search

Find public TikTok videos by keyword, hashtag, or username through Frevana's asynchronous video API. Requires Bash and Python 3.9+; no browser extension, daemon, Apify SDK, or provider token is needed.

Workflow

1. Choose exactly one source type per task: --query/--keyword for keyword video searches, --hashtag for topic videos (without #), or --username for videos from specific creators (without @, not profile URLs). Repeat the chosen flag for 1–5 values. Resolve {baseDir} to this skill's folder and prefer scripts/tiktok_video_search.sh. Keyword mode sends search_queries with search_section=/video; hashtag mode sends hashtags; username mode sends profiles and uses the Server's original-video feed with latest-first sorting. Exact post collection, Top/user search, and ads are separate workflows.
2. Authenticate with FREVANA_TOKEN or FREVANA_API_KEY, or a one-time --token/--api-key. Explicit credentials override environment credentials; otherwise the token takes precedence. Never print credentials.
3. Use run to submit and wait, or create to return immediately. Keep the printed client_task_id and returned task_id. Downloads are enabled by the Server by default and incur extra cost. For metadata-only requests, pass --should-download-videos false. Leave other paid enrichment off unless requested; see references/api.md for parameters and cost semantics.
4. Follow next_poll_after_ms. Fetch results only when status=READY and result_available=true. Stop on FAILED, REVIEW_REQUIRED, RESULT_EXPIRED, or a zero polling interval without available results. Resume timeouts with wait --task-id; never automatically submit another paid task. If creation is uncertain, retry only with the same client_task_id and identical options. Changed inputs under that ID return HTTP 409.
5. Preserve the JSON file and summarize relevant videos unless the user asks for raw JSON. Useful fields include id, text, webVideoUrl, authorMeta, playCount, diggCount, and video_url. Keep IDs as strings, missing metrics as unknown, and individual errorCode records visible. A ready task does not guarantee every item has a downloaded video.

Commands