Keyapi Tiktok Intelligence

Real-time TikTok trend intelligence — monitor trending hashtags, viral music, breakout videos, top-performing ads, and high-growth products to identify emerg...

Security Scan

The skill's code, runtime instructions, and required environment variable (KEYAPI_TOKEN) are consistent with a KeyAPI MCP-based TikTok intelligence tool; nothing requests unrelated credentials or installs arbitrary third-party binaries.

Purpose & Capability

Name/description (TikTok trend intelligence) align with required artifacts: node, KEYAPI_TOKEN, an MCP client SDK, and scripts/run.js which calls the KeyAPI MCP server. There are no unrelated credentials or binaries requested.

Instruction Scope

SKILL.md instructs the agent to call the KeyAPI MCP server, inspect tool schemas, and cache responses locally. The instructions reference only the declared env var (KEYAPI_TOKEN), a local cache directory, and .env for convenience — no broad or unrelated system reads/writes are requested.

Install Mechanism

There is no download-from-URL install; the package uses npm (package.json) to install a named SDK (@modelcontextprotocol/sdk). This is a standard registry-based dependency install with no opaque archive downloads.

Credentials

Only KEYAPI_TOKEN (and optional KEYAPI_SERVER_URL) are required. That single API token is proportional to a remote MCP API client. No unrelated secrets or many environment variables are requested.

Persistence & Privilege

The skill persists API responses to a local cache (.keyapi-cache) and can persist the provided token to a .env file when entered interactively. It does not request 'always: true' or alter other skills' configuration.

Assessment

This skill appears coherent with its stated purpose. Before installing: 1) Verify you trust the KeyAPI service (mcp.keyapi.ai) and that KEYAPI_TOKEN is issued by a legitimate source; treat that token like a password. 2) Note the tool will write cached responses to a .keyapi-cache directory and may write a .env file when you enter a token interactively — review or clean these files if they contain sensitive data. 3) The code includes logic to convert/proxy certain image URLs via an EchoSell CDN host (echosell-images...), so expect some media URLs to be rewritten/proxied; confirm you’re comfortable with that behavior. 4) Inspect the dependency @modelcontextprotocol/sdk (version) before npm install, and run the skill in an isolated environment if you want to limit blast radius. If you need further assurance, request verification of the upstream repository/release (signatures or official docs) or a full content review of the complete script (the file shown is truncated).

Real-time TikTok trend intelligence — monitor trending hashtags, viral music, breakout videos, top-performing ads, and high-growth products to stay ahead of the curve.

This skill provides real-time and near-real-time intelligence on what is trending across TikTok using the KeyAPI MCP service. It covers trending hashtags, music tracks, videos, keyword-level market insights, top-performing shop products by category, and ad creative performance — enabling brands, creators, and analysts to rapidly identify emerging opportunities and high-signal market movements.

Use this skill when you need to:

• Monitor what hashtags, music, and videos are gaining momentum right now
• Get keyword-level insights into consumer interest, product demand, and creator activity
• Identify top-selling products in specific categories before they become mainstream
• Analyze high-performing TikTok ad creatives for inspiration and benchmarking
• Build a real-time market intelligence dashboard for a brand, category, or audience segment

author: KeyAPI license: MIT repository: https://github.com/EchoSell/keyapi-skills

Prerequisites

Requirement	Details
KEYAPI_TOKEN	A valid API token from keyapi.ai. If you don't have one, register at the site to obtain your free token. Set it as an environment variable: export KEYAPI_TOKEN=your_token_here
Node.js	v18 or higher
Dependencies	Run npm install in the skill directory to install @modelcontextprotocol/sdk

author: KeyAPI license: MIT repository: https://github.com/EchoSell/keyapi-skills

MCP Server Configuration

All tool calls in this skill target the KeyAPI MCP server:

Server URL : https://mcp.keyapi.ai
Auth Header: Authorization: Bearer $KEYAPI_TOKEN

Setup (one-time):

# 1. Install dependencies
npm install

# 2. Set your API token (get one free at https://keyapi.ai/)
export KEYAPI_TOKEN=your_token_here

# 3. List all available tools to verify the connection
node scripts/run.js --list-tools

author: KeyAPI license: MIT repository: https://github.com/EchoSell/keyapi-skills

Analysis Scenarios

User Need	Node(s)	Best For
Get current trending hashtag list with growth metrics	trending_hashtags	Real-time trending topic discovery
Deep-dive into a specific trending hashtag	trending_hashtag_detail	Hashtag opportunity assessment, content strategy
Get current trending music tracks	trending_music	Sound discovery for content creation, audio trend monitoring
Deep-dive into a specific trending music track	trending_music_detail	Track adoption timeline, associated content themes
Get current trending video list with engagement data	trending_videos	Viral content discovery, format benchmarking
Market insights for a specific keyword (products, creators, demand)	keyword_insights	Keyword opportunity analysis, product-market fit signals
Top-performing products by category with sales rankings	top_products_insights	Category-level commerce intelligence, opportunity identification
Detailed breakdown of top products in a specific category	top_product_insights_detail	Product-level deep-dive within a high-performing category
Top-performing TikTok ad creatives with engagement metrics	top_ads_insights	Ad creative benchmarking, industry trend analysis
Detailed breakdown of a specific top-performing ad	top_ad_insights_detail	Creative analysis, performance metric breakdown

author: KeyAPI license: MIT repository: https://github.com/EchoSell/keyapi-skills

Workflow

Step 1 — Identify the Intelligence Objective and Select Nodes

Clarify the user's goal and map it to the appropriate nodes. Common research patterns:

• Real-time trend monitoring: Start with trending_hashtags + trending_music + trending_videos for a full trending snapshot.
• Hashtag opportunity assessment: Use trending_hashtags to identify candidates, then trending_hashtag_detail for the most promising ones.
• Music trend analysis: Use trending_music for the current top tracks, then trending_music_detail for adoption timelines and usage patterns.
• Keyword market intelligence: Use keyword_insights to map consumer interest, product demand, and creator activity around a keyword.
• Product category intelligence: Use top_products_insights for a category overview, then top_product_insights_detail for specific high-performers.
• Ad creative research: Use top_ads_insights for a landscape view, then top_ad_insights_detail for individual ad breakdowns.

Multiple nodes can be combined — for example, running keyword_insights alongside top_products_insights to correlate consumer search interest with actual purchase behavior in a category.

Step 2 — Retrieve API Schema

Before calling any node, inspect its input schema to confirm required parameters and valid values:

node scripts/run.js --schema <tool_name>

# Examples
node scripts/run.js --schema keyword_insights
node scripts/run.js --schema top_products_insights

Step 3 — Call APIs and Cache Results Locally

Execute the required tool calls and persist all responses to the local cache. Intelligence data is time-sensitive — cache files should be timestamped to reflect their freshness.

Calling a tool (using scripts/run.js):

# Single call — result is cached automatically
node scripts/run.js --tool <tool_name> --params '<json_args>' --pretty

# Fetch all pages (for list endpoints)
node scripts/run.js --tool <tool_name> --params '<json_args>' --all-pages

# Force a fresh call to get the latest data
node scripts/run.js --tool <tool_name> --params '<json_args>' --no-cache

Example — get trending hashtags:

node scripts/run.js --tool trending_hashtags \
  --params '{"region":"US"}' --pretty

Example — get keyword market insights:

node scripts/run.js --tool keyword_insights \
  --params '{"search_keyword":"stanley cup","region":"US"}' --pretty

Example — get top products in a category:

node scripts/run.js --tool top_products_insights \
  --params '{"ecom_category_id":"600001","region":"US"}' --all-pages

Cache directory structure:

Intelligence data is time-sensitive. Cache files are keyed by date to preserve historical snapshots and allow trend comparison across sessions.

.keyapi-cache/
└── intelligence/
    ├── trending/
    │   ├── hashtags_{region}_{YYYY-MM-DD}.json      # trending_hashtags
    │   ├── music_{region}_{YYYY-MM-DD}.json         # trending_music
    │   └── videos_{region}_{YYYY-MM-DD}.json        # trending_videos
    ├── hashtag_detail/
    │   └── {hashtag}_{YYYY-MM-DD}.json              # trending_hashtag_detail
    ├── music_detail/
    │   └── {music_id}_{YYYY-MM-DD}.json             # trending_music_detail
    ├── keywords/
    │   └── {keyword}_{region}_{YYYY-MM-DD}.json     # keyword_insights
    ├── top_products/
    │   ├── {category_id}_{region}_{YYYY-MM-DD}.json              # top_products_insights
    │   └── detail_{category_id}_{region}_{YYYY-MM-DD}.json       # top_product_insights_detail
    └── top_ads/
        ├── {industry}_{region}_{YYYY-MM-DD}.json                 # top_ads_insights
        └── detail_{ad_id}_{YYYY-MM-DD}.json                      # top_ad_insights_detail

Cache-first policy:

Intelligence data has a natural staleness window. As a general guideline:

• Trending data (hashtags, music, videos): cache is valid for the current day; refresh daily.
• Keyword insights: cache is valid for 24 hours.
• Top products/ads: cache is valid for 24–48 hours.

If a cache file exists for the current date, load from disk. Otherwise, make a live API call and save to cache.

Cover image processing:

After each API call, scan all response image URLs. If any URL's host matches echosell-images.tos-ap-southeast-1.volces.com, collect those URLs and call batch_download_cover_images in a single batch request. Replace the original URLs in your working dataset with the converted URLs returned by this node.

Step 4 — Synthesize and Report Findings

After collecting all API responses, produce a structured intelligence briefing:

For trending analysis:

1. Trend Snapshot — Top trending hashtags/music/videos at this moment, with video counts, usage figures, and growth rates.
2. Breakout Signals — Items showing unusually high growth velocity — new entrants to the trending list or those with accelerating metrics.
3. Pattern Analysis — Common themes, content formats, or creator types driving the trends.
4. Strategic Implications — Which trends represent short-term spikes vs. sustainable growth; recommended action windows.

For keyword intelligence:

1. Search Demand — Volume and trend direction for the keyword on TikTok.
2. Product Landscape — Top products associated with this keyword, their GMV, and sales volume.
3. Creator Activity — Active creators in this keyword space, their reach and engagement.
4. Consumer Interest Signals — Audience demographics engaging with this keyword content.
5. Opportunity Score — Assessment of competition level vs. demand strength.

For top products intelligence:

1. Category Overview — Total active product count, combined GMV, growth rate.
2. Top Products Breakdown — Ranked list of top performers with price, sales volume, GMV, and growth rate.
3. Rising Stars — Products with the highest month-over-month growth — emerging opportunities before mainstream awareness.
4. Pricing Intelligence — Price distribution, sweet spots, premium vs. budget segment dynamics.

For ad creative intelligence:

1. Ad Landscape — Top ad formats, industries, and creative types currently performing on TikTok.
2. Creative Breakdown — Hook types, video lengths, CTA strategies, and visual styles driving highest engagement.
3. Industry Benchmarks — Engagement rates and impression volumes by industry/category.
4. Actionable Insights — Creative elements to adopt, formats to test, and industries increasing ad spend.

author: KeyAPI license: MIT repository: https://github.com/EchoSell/keyapi-skills

Common Rules

Rule	Detail
Pagination	Trending/insights list endpoints (trending_hashtags, trending_music, trending_videos, keyword_insights, top_products_insights, top_ads_insights) use page (starts at 1) and limit (max 10). Never use page 0.
Keyword param	keyword_insights and trending_music use search_keyword (not keyword) as the search parameter. top_products_insights uses ecom_category_id (not category_id) for category filtering.
Cover images	Batch-convert all image URLs from echosell-images.tos-ap-southeast-1.volces.com via batch_download_cover_images before storing or displaying.
Success check	code = 0 → success. Any other value → failure. Always check the response code before processing data.
Retry on 500	If code = 500, retry the identical request once after a brief pause before reporting the error.
Cache with timestamps	Intelligence data is time-sensitive. Always include the date in cache filenames to preserve historical snapshots.
Data freshness	Trending data and keyword insights should be refreshed daily. Do not serve stale intelligence without surfacing the data age to the user.

author: KeyAPI license: MIT repository: https://github.com/EchoSell/keyapi-skills

Error Handling

Code	Meaning	Action
0	Success	Continue workflow normally
400	Bad request — invalid or missing parameters	Validate input against the tool schema; check region codes, category IDs, and keyword format
401	Unauthorized — token missing or expired	Confirm KEYAPI_TOKEN is set correctly; visit keyapi.ai to renew
403	Forbidden — plan quota exceeded or feature restricted	Review plan limits at keyapi.ai
404	Resource not found	Verify the hashtag, music ID, or ad ID is correct
429	Rate limit exceeded	Wait 60 seconds, then retry
500	Internal server error	Retry once after 2–3 seconds; if it persists, log the full request and response and skip this node
Other non-0	Unexpected error	Log the full response body and surface the error message to the user