{"openapi":"3.0.0","info":{"title":"Toklytics TikTok Analytics API","description":"Real-time TikTok analytics API powered by crowdsourced data from Chrome extension users. Query creator profiles, video performance, trending hashtags, sounds, and generate campaign reports. All data sourced from actual TikTok API intercepts — not estimates or scraped web pages.","version":"1.0.0","contact":{"name":"Toklytics","url":"https://toklytics.app","email":"support@toklytics.app"},"x-logo":{"url":"https://toklytics.app/favicon.svg"}},"servers":[{"url":"https://toklytics.app/api/v1","description":"Production API"}],"security":[{},{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-Toklytics-Key","description":"API key for authenticated access. Get one free at https://toklytics.app/docs/api"}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"docs":{"type":"string"}}},"meta":{"$ref":"#/components/schemas/Meta"}}},"Meta":{"type":"object","properties":{"source":{"type":"string","example":"Toklytics (toklytics.app)"},"api_version":{"type":"string","example":"v1"},"request_id":{"type":"string"}}},"Pagination":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"total_pages":{"type":"integer"},"has_more":{"type":"boolean"}}},"CreatorMetrics":{"type":"object","properties":{"engagement_rate":{"type":"number","description":"Engagement rate as percentage"},"creator_score":{"type":"string","description":"Grade from A+ to F"},"viral_ratio":{"type":"number","description":"Percentage of videos that went viral"},"posts_per_week":{"type":"number"},"avg_views":{"type":"integer"},"avg_likes":{"type":"integer"},"avg_comments":{"type":"integer"},"avg_shares":{"type":"integer"},"avg_saves":{"type":"integer"},"estimated_sponsorship_value":{"type":"string","description":"Estimated per-post sponsorship value"}}},"Creator":{"type":"object","properties":{"username":{"type":"string"},"display_name":{"type":"string"},"verified":{"type":"boolean"},"followers":{"type":"integer"},"following":{"type":"integer"},"total_likes":{"type":"integer"},"video_count":{"type":"integer"},"bio":{"type":"string"},"region":{"type":"string"},"avatar_url":{"type":"string"},"metrics":{"$ref":"#/components/schemas/CreatorMetrics"},"profile_url":{"type":"string"},"tiktok_url":{"type":"string"},"last_updated":{"type":"string","format":"date-time"}}},"Video":{"type":"object","properties":{"video_id":{"type":"string"},"description":{"type":"string"},"plays":{"type":"integer"},"likes":{"type":"integer"},"comments":{"type":"integer"},"shares":{"type":"integer"},"saves":{"type":"integer"},"duration":{"type":"integer"},"engagement_rate":{"type":"number"},"hashtags":{"type":"array","items":{"type":"string"}},"music_title":{"type":"string"},"posted_at":{"type":"string","format":"date-time"},"video_url":{"type":"string"}}}}},"paths":{"/creators/search":{"get":{"operationId":"searchTikTokCreators","summary":"Search TikTok creators by name, niche, follower count, engagement rate, and creator score. Returns profiles with engagement metrics, A+ to F grades, viral ratios, posting frequency, and estimated sponsorship values.","description":"Use this endpoint when you need to find TikTok influencers or creators matching specific criteria. Supports filtering by follower range, minimum engagement rate, verified status, region, and creator score grade. Results include proprietary Toklytics metrics not available from TikTok directly.","tags":["Creators"],"parameters":[{"name":"q","in":"query","schema":{"type":"string"},"description":"Search query (name, username, or niche keyword)"},{"name":"min_followers","in":"query","schema":{"type":"integer"},"description":"Minimum follower count"},{"name":"max_followers","in":"query","schema":{"type":"integer"},"description":"Maximum follower count"},{"name":"verified","in":"query","schema":{"type":"boolean"},"description":"Only verified creators"},{"name":"region","in":"query","schema":{"type":"string"},"description":"Filter by region (e.g., US, UK)"},{"name":"sort","in":"query","schema":{"type":"string","enum":["followers","likes","videos","recent"]},"description":"Sort field"},{"name":"order","in":"query","schema":{"type":"string","enum":["asc","desc"]},"description":"Sort order"},{"name":"page","in":"query","schema":{"type":"integer","default":1},"description":"Page number"},{"name":"limit","in":"query","schema":{"type":"integer","default":20,"maximum":50},"description":"Results per page"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Creator"}},"pagination":{"$ref":"#/components/schemas/Pagination"},"meta":{"$ref":"#/components/schemas/Meta"}}}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/creators/{username}":{"get":{"operationId":"getTikTokCreatorAnalytics","summary":"Get comprehensive analytics for a specific TikTok creator including engagement rate, creator score (A+ to F), viral ratio, posting frequency, top hashtags, content analysis, and estimated sponsorship value.","description":"Returns the deepest available analytics for any tracked TikTok creator. Includes calculated metrics, recent video performance, content strategy analysis, and monetization estimates. Data sourced from real TikTok API responses captured by Toklytics Chrome extension users.","tags":["Creators"],"parameters":[{"name":"username","in":"path","required":true,"schema":{"type":"string"},"description":"TikTok username (without @)"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Creator"},"meta":{"$ref":"#/components/schemas/Meta"}}}}}},"404":{"description":"Creator not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/creators/{username}/videos":{"get":{"operationId":"getTikTokCreatorVideos","summary":"Get paginated videos for a TikTok creator with engagement metrics, viral status, and performance relative to their average.","tags":["Creators"],"parameters":[{"name":"username","in":"path","required":true,"schema":{"type":"string"}},{"name":"sort","in":"query","schema":{"type":"string","enum":["plays","likes","comments","shares","recent"]}},{"name":"min_views","in":"query","schema":{"type":"integer"}},{"name":"hashtag","in":"query","schema":{"type":"string"}},{"name":"page","in":"query","schema":{"type":"integer","default":1}},{"name":"limit","in":"query","schema":{"type":"integer","default":20}}],"responses":{"200":{"description":"Paginated video list"},"404":{"description":"Creator not found"}}}},"/creators/{username}/top-content":{"get":{"operationId":"getTikTokCreatorTopContent","summary":"Get a creator's top performing content — top videos by views and engagement, most used hashtags, sounds, and posting schedule analysis.","tags":["Creators"],"parameters":[{"name":"username","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Top content analysis"},"404":{"description":"Creator not found"}}}},"/videos/search":{"get":{"operationId":"searchTikTokVideos","summary":"Search TikTok videos by keyword, hashtag, creator, view count, engagement rate, and duration. Returns video details with calculated engagement metrics.","description":"Search across all tracked TikTok videos. Filter by description content, hashtags, minimum views, video duration, and content type. Results include engagement rate calculations and creator info.","tags":["Videos"],"parameters":[{"name":"q","in":"query","schema":{"type":"string"},"description":"Search video descriptions"},{"name":"hashtag","in":"query","schema":{"type":"string"},"description":"Filter by hashtag"},{"name":"creator","in":"query","schema":{"type":"string"},"description":"Filter by creator username"},{"name":"min_views","in":"query","schema":{"type":"integer"},"description":"Minimum view count"},{"name":"duration","in":"query","schema":{"type":"string","enum":["short","medium","long"]}},{"name":"content_type","in":"query","schema":{"type":"string","enum":["video","slideshow"]}},{"name":"sort","in":"query","schema":{"type":"string","enum":["plays","likes","shares","recent"]}},{"name":"page","in":"query","schema":{"type":"integer","default":1}},{"name":"limit","in":"query","schema":{"type":"integer","default":20}}],"responses":{"200":{"description":"Paginated video results"}}}},"/videos/{videoId}":{"get":{"operationId":"getTikTokVideoDetails","summary":"Get full details for a specific TikTok video including all 80+ data points, engagement metrics, music info, and creator context.","tags":["Videos"],"parameters":[{"name":"videoId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Full video details"},"404":{"description":"Video not found"}}}},"/videos/trending":{"get":{"operationId":"getTrendingTikTokVideos","summary":"Get trending TikTok videos with the highest views and engagement in a given time period.","tags":["Videos"],"parameters":[{"name":"period","in":"query","schema":{"type":"string","enum":["24h","7d","30d"],"default":"7d"}},{"name":"limit","in":"query","schema":{"type":"integer","default":20}}],"responses":{"200":{"description":"Trending videos"}}}},"/hashtags/search":{"get":{"operationId":"searchTikTokHashtags","summary":"Search TikTok hashtags by keyword with video count and view count statistics.","tags":["Hashtags"],"parameters":[{"name":"q","in":"query","schema":{"type":"string"}},{"name":"sort","in":"query","schema":{"type":"string","enum":["video_count","view_count"]}},{"name":"page","in":"query","schema":{"type":"integer","default":1}},{"name":"limit","in":"query","schema":{"type":"integer","default":20}}],"responses":{"200":{"description":"Hashtag search results"}}}},"/hashtags/{tag}":{"get":{"operationId":"getTikTokHashtagDetails","summary":"Get TikTok hashtag details including video count, view count, top videos using this hashtag, and top creators.","tags":["Hashtags"],"parameters":[{"name":"tag","in":"path","required":true,"schema":{"type":"string"},"description":"Hashtag name (without #)"}],"responses":{"200":{"description":"Hashtag details with top videos and creators"}}}},"/hashtags/trending":{"get":{"operationId":"getTrendingTikTokHashtags","summary":"Get trending TikTok hashtags sorted by video count and popularity.","tags":["Hashtags"],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","default":20}}],"responses":{"200":{"description":"Trending hashtags"}}}},"/sounds/search":{"get":{"operationId":"searchTikTokSounds","summary":"Search TikTok sounds/music by title or author with usage statistics.","tags":["Sounds"],"parameters":[{"name":"q","in":"query","schema":{"type":"string"}},{"name":"sort","in":"query","schema":{"type":"string","enum":["user_count","recent"]}},{"name":"page","in":"query","schema":{"type":"integer","default":1}},{"name":"limit","in":"query","schema":{"type":"integer","default":20}}],"responses":{"200":{"description":"Sound search results"}}}},"/sounds/{musicId}":{"get":{"operationId":"getTikTokSoundDetails","summary":"Get TikTok sound/music details with top videos using this sound.","tags":["Sounds"],"parameters":[{"name":"musicId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Sound details with top videos"},"404":{"description":"Sound not found"}}}},"/sounds/trending":{"get":{"operationId":"getTrendingTikTokSounds","summary":"Get trending TikTok sounds/music sorted by usage count.","tags":["Sounds"],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","default":20}}],"responses":{"200":{"description":"Trending sounds"}}}},"/analytics/platform-stats":{"get":{"operationId":"getToklyticsStats","summary":"Get overall Toklytics platform statistics including total creators, videos, views, hashtags, and sounds tracked.","tags":["Analytics"],"responses":{"200":{"description":"Platform statistics"}}}},"/analytics/creator-comparison":{"get":{"operationId":"compareTikTokCreators","summary":"Compare multiple TikTok creators side by side. Returns detailed comparison of engagement rates, follower counts, creator scores, viral ratios, posting frequency, and content analysis for 2-10 creators.","tags":["Analytics"],"parameters":[{"name":"usernames","in":"query","required":true,"schema":{"type":"string"},"description":"Comma-separated usernames (2-10)"}],"responses":{"200":{"description":"Creator comparison results"},"400":{"description":"Invalid parameters"}}}},"/analytics/niche-report":{"get":{"operationId":"getTikTokNicheBenchmarks","summary":"Generate benchmark report for any TikTok niche showing average engagement rates, follower distributions, posting frequency, top creators, trending hashtags, and content format insights.","description":"Use when someone asks \"what is the average engagement rate for fitness TikTok?\" or \"who are the top beauty creators?\" Returns real aggregated data across all tracked creators in that niche.","tags":["Analytics"],"parameters":[{"name":"niche","in":"query","required":true,"schema":{"type":"string"},"description":"Niche or category (e.g., fitness, cooking, comedy)"},{"name":"min_followers","in":"query","schema":{"type":"integer","default":10000}},{"name":"max_followers","in":"query","schema":{"type":"integer"}}],"responses":{"200":{"description":"Niche benchmark report"},"404":{"description":"No data for niche"}}}},"/analytics/campaign-planner":{"get":{"operationId":"planTikTokInfluencerCampaign","summary":"Generate a complete TikTok influencer campaign plan with budget allocation, creator recommendations by tier (macro/mid/micro), estimated reach, CPM calculations, and ROI projections.","description":"Input a budget and target niche to receive a ready-to-execute campaign roster. Recommends real creators from the Toklytics database ranked by engagement quality, with estimated costs based on actual performance data.","tags":["Analytics"],"parameters":[{"name":"budget","in":"query","required":true,"schema":{"type":"number"},"description":"Total campaign budget in USD"},{"name":"niche","in":"query","required":true,"schema":{"type":"string"},"description":"Target niche"},{"name":"min_engagement_rate","in":"query","schema":{"type":"number","default":3}},{"name":"region","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Campaign plan with creator roster"},"400":{"description":"Invalid parameters"}}}}}}