> ## Documentation Index > Fetch the complete documentation index at: https://developers.gopher-ai.com/llms.txt > Use this file to discover all available pages before exploring further. # TikTok All job types use the `/api/v1/search/live` POST endpoint and follow the same structure: a top-level `type` to define the data source, and a set of `arguments` defining the parameters of the job. Search across TikTok videos by query Find videos that are trending Transcribe TikTok videos ### `searchbyquery` Searches TikTok content based on keywords, hashtags, or phrases. This job type allows you to find specific content across the TikTok platform. **Use Cases:** * Finding content about specific topics * Discovering videos with certain hashtags * Researching content trends for particular keywords ### `searchbytrending` Retrieves trending TikTok content sorted by various engagement metrics. This job type helps you discover what's currently popular on TikTok. **Use Cases:** * Monitoring viral content * Tracking engagement trends * Analyzing popular content by country * Understanding what content formats are gaining traction ## Parameters ### Common Parameters | Parameter | Type | Required | Default | Description | | ----------- | ------- | -------- | ------- | --------------------------------------------------- | | `type` | string | Yes | - | The job type: `searchbyquery` or `searchbytrending` | | `max_items` | integer | No | `10` | Maximum number of items to return | ### `searchbyquery` Parameters | Parameter | Type | Required | Default | Description | | --------- | -------------- | -------- | ------- | ---------------------------------------------- | | `search` | array\[string] | Yes | - | Array of search queries (keywords or hashtags) | ### `searchbytrending` Parameters | Parameter | Type | Required | Default | Description | | -------------- | ------ | -------- | ------- | ------------------------------------------------------------------------------------------- | | `sort_by` | string | No | `vv` | Sort trending content by metric. See [Sort Options](#sort-options) | | `period` | string | No | `7` | Time period for trending content: `"7"` (week) or `"30"` (month) | | `country_code` | string | No | `"US"` | Country code for regional trending content. See [Supported Countries](#supported-countries) | ## Sort Options The `sort_by` parameter for trending searches supports the following values: | Value | Description | Best For | | --------- | -------------------------------- | ----------------------------- | | `vv` | Sort by views/trending score | Finding viral content | | `like` | Sort by number of likes | High engagement content | | `comment` | Sort by number of comments | Discussion-generating content | | `repost` | Sort by number of reposts/shares | Highly shareable content | ### `searchbyquery` Searches for TikTok videos based on keywords and phrases #### Basic Keyword Search ```json theme={null} { "type": "tiktok", "arguments": { "type": "searchbyquery", "search": ["AI", "crypto"], "max_items": 10 } } ``` #### Hashtag Search ```json theme={null} { "type": "tiktok", "arguments": { "type": "searchbyquery", "search": ["#artificialintelligence", "#machinelearning", "#tech"], "max_items": 25 } } ``` #### Multi-Topic Search ```json theme={null} { "type": "tiktok", "arguments": { "type": "searchbyquery", "search": [ "sustainable fashion", "eco friendly clothing", "thrift haul" ], "max_items": 50 } } ``` ### `searchbytrending` Searches for TikTok videos based on popular trends #### Most Shared Content (Last Week) ```json theme={null} { "type": "tiktok", "arguments": { "type": "searchbytrending", "sort_by": "repost", "period": "7", "max_items": 10 } } ``` #### Most Commented Videos (Last Month) ```json theme={null} { "type": "tiktok", "arguments": { "type": "searchbytrending", "sort_by": "comment", "period": "30", "max_items": 20 } } ``` #### Regional Trending Content ```json theme={null} { "type": "tiktok", "arguments": { "type": "searchbytrending", "sort_by": "vv", "period": "7", "country_code": "JP", "max_items": 15 } } ``` #### Most Liked Content by Country ```json theme={null} { "type": "tiktok", "arguments": { "type": "searchbytrending", "sort_by": "like", "period": "7", "country_code": "BR", "max_items": 25 } } ``` ## Use Case Examples ### Content Research Discover what topics are gaining traction: ```json theme={null} { "type": "tiktok", "arguments": { "type": "searchbyquery", "search": ["climate change", "sustainability", "green energy"], "max_items": 30 } } ``` ### Competitive Analysis Monitor trending content in specific markets: ```json theme={null} { "type": "tiktok", "arguments": { "type": "searchbytrending", "sort_by": "vv", "period": "7", "country_code": "KR", "max_items": 20 } } ``` ### Engagement Analysis Find highly engaging content formats: ```json theme={null} { "type": "tiktok", "arguments": { "type": "searchbytrending", "sort_by": "comment", "period": "30", "country_code": "US", "max_items": 50 } } ``` ## Supported Countries The TikTok API supports trending content from the following countries: ### Americas * `US` - United States * `CA` - Canada * `BR` - Brazil ### Europe * `GB` - United Kingdom * `FR` - France * `DE` - Germany * `IT` - Italy * `ES` - Spain * `RU` - Russia * `TR` - Turkey ### Asia-Pacific * `AU` - Australia * `JP` - Japan * `KR` - South Korea * `SG` - Singapore * `MY` - Malaysia * `ID` - Indonesia * `TH` - Thailand * `PH` - Philippines * `VN` - Vietnam * `TW` - Taiwan * `IL` - Israel ### Middle East & Africa * `AE` - United Arab Emirates * `SA` - Saudi Arabia * `EG` - Egypt ## Best Practices ### 1. Query Optimization * Use specific keywords for targeted results * Combine related search terms in a single request * Include both general terms and specific hashtags ### 2. Trending Analysis * Use `period: "7"` for current trends * Use `period: "30"` for more stable trend analysis * Compare different `sort_by` metrics to understand content performance ### 3. Regional Insights * Always specify `country_code` when analyzing regional markets * Compare trending content across different countries * Consider cultural context when interpreting results ### 4. Data Collection * Set appropriate `max_items` based on your analysis needs * For comprehensive analysis, consider multiple queries with different parameters * Cache results to avoid redundant API calls ## Response Data While the exact response structure may vary, typical TikTok data includes: * **Video Details**: Title, description, hashtags, duration * **Engagement Metrics**: Views, likes, comments, shares/reposts * **Creator Information**: Username, follower count * **Timestamps**: Creation date, trending period * **Media URLs**: Video URLs, thumbnail images * **Audio Information**: Music/sound used in the video ## Limitations * Search results are subject to TikTok's algorithm and availability * Historical trending data is limited to 7 or 30-day periods * Country-specific trending may not reflect global trends * Content availability may vary by region * Maximum item limits apply to prevent excessive API usage ## Error Handling ### Common Error Scenarios #### Invalid Country Code Ensure the `country_code` parameter uses one of the supported country codes listed above. #### Invalid Sort Option The `sort_by` parameter must be one of: `vv`, `like`, `comment`, or `repost`. #### Invalid Period The `period` parameter only accepts `"7"` or `"30"` as string values. #### Missing Required Parameters * `searchbyquery` requires the `search` array * `searchbytrending` has all optional parameters but benefits from explicit configuration ## Notes * The `vv` sort option represents TikTok's trending/view score algorithm * Period values must be strings (`"7"` not `7`) * Search queries can include hashtags with or without the `#` symbol * Multiple search terms in the `search` array will return combined results