Keyapi Tiktok Intelligence

keyapi-tiktok-intelligence

> 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:

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:

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 
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  --params '' --pretty
Fetch all pages (for list endpoints)
node scripts/run.js --tool  --params '' --all-pages
Force a fresh call to get the latest data
node scripts/run.js --tool  --params '' --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:

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 |

| 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