🎯 TikTok Competitive Insight Analysis
1. Capability Overview
💡 Value in a nutshell: One conversational command to get TikTok's public video/author/comment data, output as structured JSON—for influencer screening, data analysis, market research, sentiment monitoring, viral topic identification, benchmark account monitoring, comment sentiment analysis, and trend tracking. No more manual TikTok scrolling.
| Capability | Entry Script | Required Parameters | Returns |
|---|---|---|---|
| Keyword Search | scripts/tiktok/search-cli.js | --keyword | Video list: author, likes/comments/shares/favorites, tags, play URL |
| Creator Videos | scripts/tiktok/post-cli.js | --url (profile or username) | Public video list for that creator (supports Latest / Most Popular sorting) |
| Video Comments | scripts/tiktok/comment-cli.js | --url (video link or ID) | Comment text, commenter, like count, reply count |
Target Users
- 🎯 Brands — Ride trending topics for organic content
- 🏢 MCN Agencies — Discover high-engagement potential accounts
- ✍️ Content Creators — Find benchmark samples, get creative inspiration
- 📊 Content Operators — Weekly report topics and competitor analysis
Prerequisite: Must be executed from the skill root directory, and the environment variable
GUAIKEI_API_TOKENmust be configured. If not configured, all commands return exit code3,error_code=AUTH_REQUIRED—in this case, directly prompt the user to configure the Token, do not retry, do not change parameters.
2. When to Call / When Not to Call
2.1 Should Call
- User wants to query public TikTok content (videos / images / authors / comments / trends).
- User wants to conduct viral topic research, competitor account monitoring, influencer screening, comment sentiment analysis, content style analysis.
- User has provided TikTok keywords, video links, or creator profile links, and expects structured data.
- User wants to summarize, compare, sort, cluster, or generate reports/tables after receiving the data.
2.2 Should Not Call
- User only needs copy/text/script, not TikTok data.
- The platform is not TikTok but another platform (Douyin, Xiaohongshu, Bilibili, Weibo, WeChat Official Accounts) → Route to the corresponding skill. This skill only handles TikTok.
- Login, private, or hidden data is requested → Not supported.
- Both a keyword and an identifiable link exist, and the intent is unclear → Ask for clarification first, do not guess.
2.3 Capability Boundaries (Explicitly Not Done)
Write operations such as posting, liking, commenting, following, or sending direct messages are not supported; no accounts are logged into; phone numbers, locations, private messages, or other private fields are not collected; marketing decisions are not made on behalf of the user—the responsibility is to retrieve the data; analysis is left to higher levels.
3. Call Routing (Determine First, Then Execute)
| User Intent | Script | Keywords for Judgment |
|---|---|---|
| Search keywords, find specific content, find viral content | search-cli | search / find / keyword / viral / most popular |
| View a creator/influencer/celebrity's videos, profile, recent posts | post-cli | videos / profile / account / creator / influencer / KOL |
| View comments on a specific video | comment-cli | comments / replies / opinions in the comment section |
3.1 Disambiguation Rules (Must Follow)
- When "video" appears alone, do not default to
post-cli.- Has "keyword" and no "comment" →
search-cli(user wants to search for this type of video). - Clearly "comments / replies on this video" →
comment-cli. - Only when "videos / profile / account / creator / influencer" appear →
post-cli.
- Has "keyword" and no "comment" →
- Comment priority is higher than videos: If a
/video/<id>link is given and the question is about comments →comment-cli; if the question is about "this person's videos" →post-cli(use@username). - User provides a
/video/<id>link but asks for "video list" → First confirm whether they want the author's videos or comments on the video.
3.2 Parameter Inference Rules
| User Statement | Parameter |
|---|---|
| Relevance / Default | --sort 0 (Search) |
| Most Popular / Most Liked / Viral / Hottest | --sort 1 (Search) |
| Most Recent / Reverse Chronological | --sort 0 (Videos) |
| Most Popular Videos | --sort 1 (Videos) |
| One day / 24 hours | --time 1 |
| One week / 7 days | --time 7 |
| One month / Three months / Six months | --time 30 / 90 / 180 |
| N items / Top N / Need N items | --limit N |
Defaults: sort=0, time=0, limit=10.
⚠️ Do not confuse
--sortfor search with--sortfor videos: The former is "Relevance / Most Likes", the latter is "Latest / Hottest".
Any parameter that falls back to its default due to an invalid value will appear in the warnings array of the output JSON. It must be displayed to the user and not treated as if the original value was used.
4. Execution Method
For complete parameter details, see references/options.md; for field-level schemas, see the 6 JSON Schema files (draft-07) under
assets/.
# Keyword Search
node scripts/tiktok/search-cli.js --keyword "AI" --sort 1 --limit 20
node scripts/tiktok/search-cli.js --keyword "AI model" --time 7 --limit 20
# Creator Videos
node scripts/tiktok/post-cli.js --url "https://www.tiktok.com/@username" --limit 30
node scripts/tiktok/post-cli.js --url "https://www.tiktok.com/@username" --sort 1 --limit 30
# Video Comments
node scripts/tiktok/comment-cli.js --url "https://www.tiktok.com/@username/video/1234567890123456789" --limit 40
Acceptable Input Formats
- Creator:
https://www.tiktok.com/@username, link with parametershttps://www.tiktok.com/@username?lang=en, or directauthor_sec_uid - Video:
https://www.tiktok.com/@username/video/<id>, short link, or direct video<id>
Execution Discipline
- Only treat stdout as machine-readable output (pure JSON); banner / progress / error logs go to stderr, do not mix them.
- It is recommended to keep a single
--limit≤ 1000. - Do not automatically relax conditions to retry after a single empty result: first inform the user of the empty result, let the user decide whether to change the keyword or relax
--time.
5. Output Contract (Required Reading for AI Agents)
All entries output the same envelope, with a consistent structure for success and failure:
{
"status": "success | empty | error",
"error_code": "OK | NO_MATCH | AUTH_REQUIRED | INVALID_KEYWORD | ...",
"message": "Human-readable explanation",
"timestamp": "2026-09-16 21:00:00",
"request": {
"command": "search",
"keyword": "AI",
"sort": 1,
"time": 0,
"limit": 20
},
"metadata": {
"skill_version": "1.0.0",
"skill_name": "tiktok-creator-videos",
"runtime_version": "22.22.2",
"execution_time": 8421
},
"results": [],
"warnings": ["Limit 99999 is invalid, reverted to 10"]
}
5.1 status Semantics
| status | Meaning | results | Action |
|---|---|---|---|
success | Data retrieved | Non-empty array | Analyze directly |
empty | Request succeeded, but no data | null | Treat as a valid result; inform user nothing was found; do not treat as a failure |
error | Request failed | null | Handle based on error_code; do not fabricate data |
5.2 Exit Codes
| Exit Code | Meaning | Agent Behavior |
|---|---|---|
0 | Success (success or empty) | Continue analysis |
1 | Runtime error (network / timeout / API exception / invalid parameter) | Display message, ask user if they want to retry with different parameters |
3 | AUTH_REQUIRED: Token missing or malformed | Stop immediately, prompt to configure GUAIKEI_API_TOKEN, prohibit retries |
5.3 Error Code Handling
| error_code | Handling Method |
|---|---|
AUTH_REQUIRED | Stop and prompt to configure Token. Prohibit retries and parameter changes. |
INVALID_KEYWORD | Indicate the keyword must be 2–100 characters, cannot contain < > " ' & or http links |
NO_MATCH | Valid empty result; suggest changing the keyword or relaxing --time |
NETWORK_ERROR | Built-in retry already attempted; if still failing, suggest checking the network; allow at most 1 manual retry |
TIMEOUT_ERROR | Built-in retry already attempted; if still failing, suggest reducing --limit and retrying |
| Others (server-side codes) | Display the original error_code + message; do not guess the meaning |
5.4 warnings Must Be Displayed
When an input parameter is invalid and is automatically reverted (e.g., --sort 9, --limit 99999), the warnings array will explain "which parameter was changed to what". This must be communicated verbatim to the user, do not pretend the parameter was applied as originally entered.
5.5 Prohibited Behaviors
- ❌ Do not fabricate, complete, or fill any data from memory.
- ❌ Do not retry, change scripts, or modify parameters upon receiving
AUTH_REQUIRED. - ❌ Do not interpret
emptyas anything other than "the content the user wants does not exist" (it does not mean the API is broken). - ❌ Do not automatically relax search conditions without user consent.
6. Result Consumption Suggestions (For Higher Quality Deliverables)
After receiving results, organize the output according to the user's original goal, rather than dumping the raw JSON:
- Topic Research → Sort by
digg_countdescending, take Top N, summarize title patterns / tags / duration distribution - Competitor Monitoring → Sort by
create_timeto analyze posting cadence, calculate update frequency and hit rate - Comment Insights → Filter by
digg_countfor high-liked comments, perform sentiment clustering, output positive/negative ratio - Influencer Screening → Cross-reference
author_nickname/ average engagement / posting frequency, provide a candidate list - For Archival Purposes → Each run automatically writes a log file; the path is indicated in the "Saved to …" line in stderr
7. Security and Compliance (Trust)
- Read-Only: Does not log into TikTok accounts; does not perform any write operations such as posting, liking, commenting, following, or sending DMs; no risk of account suspension.
- Least Privilege: Only requires one environment variable
GUAIKEI_API_TOKENnecessary for the business; does not read other local files; does not write outside the skill directory (logs are written to the system temporary directory). - Credential Protection: Token is only read from environment variables; not written to stdout, not written to logs, not exposed in error messages.
- External Data Scope (Must Be Aware): When invoked, the following is sent to
www.guaikei.com: your API Token, the search keywords or target URL/ID, and the skill name and Node version. No other local information is collected. - Data Compliance: Only collects publicly visible TikTok data (nickname, public videos, public comments). Does not include private fields such as phone numbers, locations, or DMs. Data is for personal/team internal analysis only; for external publication or commercial use, please confirm authorization and anonymize user nicknames.
- No Third-Party Dependencies: Uses only Node.js built-in modules (
https/fs/path/os/querystring); no npm dependencies, no remote script loading, noeval/child_process.
8. Frequently Asked Questions
| Scenario | Cause and Handling |
|---|---|
| Exit code 3 / AUTH_REQUIRED | Token not configured or malformed (must be 16–256 characters, alphanumeric with underscores and hyphens) |
| Search results empty | Use a more generic keyword, or set --time 0 to remove the time window; empty is a normal result, not an error |
Result count less than --limit | Server has no more results, or the single-request limit was reached; reduce to ≤ 1000 and batch |
| Persistent timeouts | Reduce --limit and retry; the script has built-in exponential backoff retry |
| Wanted "Most Popular Videos" but got reverse chronological | Use --sort 1 with post-cli |
| Parameter didn't apply / sorting differs from expectation | Check the warnings in the output; invalid parameters are silently reverted to defaults |
| Where is the log file? | See the "Saved to …" line in stderr (system temp directory tiktok-guaikei/logs/<date>/) |
9. Environment and Support
- Environment: Node.js ≥ 16.14.0, Windows / macOS / Linux;
GUAIKEI_API_TOKENis required. - Official Website: TikTok Competitive Insight Analysis (self-service Token activation, usage and API documentation).
- Change Log: references/changelog.md