# Search TikTok videos Returns the TikTok videos that match a search, with author and date, a page at a time. Use it to find content on a topic. Tool `tiktok.search.videos` on TikTok. Contract version 1, released 2026-10-27. ## Example call Over REST, send the input in the body. Over MCP, pass the same input to `call_tool`. cURL: ```bash curl https://api.voxoria.ai/v1/tools/tiktok.search.videos/calls \ -H "Authorization: Bearer $VOXORIA_API_KEY" \ -H "Content-Type: application/json" \ -d '{"input":{"query":"coffee"}}' ``` Python: ```python import os import httpx response = httpx.post( "https://api.voxoria.ai/v1/tools/tiktok.search.videos/calls", headers={"Authorization": f"Bearer {os.environ['VOXORIA_API_KEY']}"}, json={"input": {"query": "coffee"}}, timeout=60, ) print(response.json()) ``` TypeScript: ```ts const response = await fetch("https://api.voxoria.ai/v1/tools/tiktok.search.videos/calls", { method: "POST", headers: { Authorization: `Bearer ${process.env.VOXORIA_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({"input": {"query": "coffee"}}), }); console.log(await response.json()); ``` MCP (`tools/call` params): ```json { "name": "call_tool", "arguments": { "tool": "tiktok.search.videos", "input": { "query": "coffee" } } } ``` Both return [the full response](/docs/call-response.md): the call's ID, status and cost, with this tool's result in `output`. ## Input | Input | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | `query` | string | Yes | | The search query. | | `sort` | string | No | `relevance` | Order of the results: relevance (TikTok's ranking) or most_liked. One of `relevance`, `most_liked`. | | `time_range` | string | No | | Only videos published in the last day, week, month, three months or six months. One of `day`, `week`, `month`, `three_months`, `six_months`. | | `next_page_token` | string | No | | Fetches the next page. Take it from pagination.next_page_token of the previous page, and send the same query, sort and time_range. | ## Output A successful call returns these blocks in its `output`. A field not marked required can be `null`. ### videos A list of rows. Always present, possibly empty. | Field | Type | Required | Description | | --- | --- | --- | --- | | `id` | string | Yes | TikTok's numeric identifier of the video, as a string. The video is at https://www.tiktok.com/@/video/ followed by it. | | `url` | string | No | Address of the video on tiktok.com. | | `text` | string | No | The video's caption, hashtags and mentions included. | | `published_at` | string | No | When the video was published, in ISO 8601. | | `duration_ms` | integer | No | Length of the video, in milliseconds. | | `width` | integer | No | Width of the video, in pixels. | | `height` | integer | No | Height of the video, in pixels. | | `preview_image_url` | string | No | Address of the video's cover image. TikTok's media addresses expire. | | `author_id` | string | No | TikTok's numeric identifier of the author, as a string. | | `author_sec_uid` | string | No | TikTok's secure identifier of the author, which tiktok.user.videos takes as sec_uid. | | `author_username` | string | No | The author's handle, without the @. | | `author_name` | string | No | The author's display name. | | `author_image_url` | string | No | Address of the author's profile picture. | | `author_verified` | boolean | No | Whether TikTok marks the author as verified. | | `author_follower_count` | integer | No | | | `view_count` | integer | No | Number of times the video was played. | | `like_count` | integer | No | | | `comment_count` | integer | No | | | `share_count` | integer | No | | | `bookmark_count` | integer | No | Number of times the video was saved to favorites. | | `hashtags` | array of string | No | Each hashtag in the caption, without the | | `mentioned_usernames` | array of string | No | Handle of each account the caption mentions, without the @. | | `music_id` | string | No | TikTok's identifier of the video's sound. | | `music_title` | string | No | Title of the video's sound. | | `music_author_name` | string | No | Name of the artist or account the sound is credited to. | ### pagination One object. Can be `null`. How to fetch the next page. Null on the last page. | Field | Type | Required | Description | | --- | --- | --- | --- | | `next_page_token` | string | Yes | Send as next_page_token to fetch the next page. | ## Example output The `output` of a real call, each list cut to 3 items. ```json { "videos": [ { "id": "7701508267251469598", "url": "https://www.tiktok.com/@shengthomas012/video/7701508267251469598?_r=1&u_code=f0h2d6fhl6jfd8&preview_pb=0&sharer_language=en&_d=f6a00157k805b8&share_item_id=7701508267251469598&source=h5_m", "text": "As it gets colder, all I want is a warm cup of coffee ☕️🍂 These are two new go-to recipes: Hot Cinnamon Roll Latte & Cozy Brown Sugar Latte 🤎 I care more about how it tastes than how it looks 🤣😂 #CozyCoffee #FallCoffee #CoffeeRecipes #MomLife #SAHM", "published_at": "2026-10-28T00:25:43Z", "duration_ms": 10034, "width": 720, "height": 1280, "preview_image_url": "https://p19-common-sign.tiktokcdn-us.com/tos-useast8-p-0068-tx2/oYQRjfPhKA0GDpQICb1EAeFUQQhFImXfrIfyRr~tplv-tiktokx-cropcenter:500:800.jpeg?biz_tag=musically_video.video_cover&dr=9638&idc=useast8&ps=13740610&refresh_token=925320b6&shcp=9b759fb9&shp=c1333099&t=4d5b0474&x-expires=1793181600&x-signature=n9%2Foj2g7JzgU%2BNYgIMjUf3SdH%2BQ%3D", "author_id": "6544936371667080192", "author_sec_uid": "MS4wLjABAAAAq-k4lg5h1ynZB4NXaCZsb-9nUMJ_PlzXNourapAYaaNtPEpJAyTOU33MUuHSN0Us", "author_username": "shengthomas012", "author_name": "Sheng | Mama Life + Fitness 🤍", "author_image_url": "https://p19-common-sign.tiktokcdn-us.com/tos-useast8-avt-0068-tx2/4fda7d2444b0049ed8d8e7987b0d5eaf~tplv-tiktokx-cropcenter:1080:1080.webp?dr=9640&refresh_token=0a8383a8&x-expires=1793246400&x-signature=Ogmp3pfRdhM%2F0poyQWDDg6j9B8k%3D&t=4d5b0474&ps=13740610&shp=d05b14bd&shcp=34ff8df6&idc=useast8", "author_verified": null, "author_follower_count": 349, "view_count": 184, "like_count": 9, "comment_count": 0, "share_count": 0, "bookmark_count": 0, "hashtags": [ "cozycoffee", "fallcoffee", "coffeerecipes" ], "mentioned_usernames": null, "music_id": "7525794901075348279", "music_title": "Coffee Parody of Shawty by Plies and Tpain", "music_author_name": "NateDaGreat Comedy" }, { "id": "7701505515406265606", "url": "https://www.tiktok.com/@willianpaivap/video/7701505515406265606?_r=1&u_code=f0h2d6fhl6jfd8&preview_pb=0&sharer_language=en&_d=f6a00157k805b8&share_item_id=7701505515406265606&source=h5_m", "text": "Iced Coffee Chocolate 🧋 #icedcoffee #coffee #asmr #dalgona #mukbang ", "published_at": "2026-10-28T00:15:04Z", "duration_ms": 177734, "width": 576, "height": 1024, "preview_image_url": "https://p19-common-sign.tiktokcdn-us.com/tos-alisg-p-0037/oYYgfpPkAw5ETtUqR3xBBnvJsEIZIEFhODx4fD~tplv-tiktokx-cropcenter:500:800.jpeg?biz_tag=musically_video.video_cover&dr=9638&idc=useast8&ps=13740610&refresh_token=b8d80282&shcp=9b759fb9&shp=c1333099&t=4d5b0474&x-expires=1793181600&x-signature=CRGyQ81YH7RjRpYaBwqWZSGq8%2FI%3D", "author_id": "6779364289440285702", "author_sec_uid": "MS4wLjABAAAAtgL75eEoVno4j6BDx9QDIS3yYvBTNBtjBXSpFhj8M7TS3_I0SOM9ZYk6Vn4x98dh", "author_username": "willianpaivap", "author_name": "willianpaivap", "author_image_url": "https://p19-common-sign.tiktokcdn-us.com/tos-alisg-avt-0068/247d01fe92bc6002ce557c72bc661335~tplv-tiktokx-cropcenter:1080:1080.webp?dr=9640&refresh_token=8070a154&x-expires=1793246400&x-signature=NDQbg9MRQGnGqaxpoqLq6N97pJw%3D&t=4d5b0474&ps=13740610&shp=d05b14bd&shcp=34ff8df6&idc=useast8", "author_verified": null, "author_follower_count": 686046, "view_count": 146525, "like_count": 10096, "comment_count": 190, "share_count": 477, "bookmark_count": 425, "hashtags": [ "icedcoffee", "coffee", "asmr" ], "mentioned_usernames": null, "music_id": "7701505861772643090", "music_title": "original sound - willianpaivap", "music_author_name": "willianpaivap" }, { "id": "7701495455212997919", "url": "https://www.tiktok.com/@caffeinatedcowgirrl/video/7701495455212997919?_r=1&u_code=f0h2d6fhl6jfd8&preview_pb=0&sharer_language=en&_d=f6a00157k805b8&share_item_id=7701495455212997919&source=h5_m", "text": "like it’s fire i can’t lie #coffee #coffeerecipe #brownsugarshakenespresso ", "published_at": "2026-10-27T23:36:03Z", "duration_ms": 52400, "width": 720, "height": 1280, "preview_image_url": "https://p16-common-sign.tiktokcdn-us.com/tos-useast8-p-0068-tx2/oo8QWCGGEDN4oVZhTGF7AUQERAuaHrhfE8BqfT~tplv-tiktokx-cropcenter:500:800.jpeg?biz_tag=musically_video.video_cover&dr=9638&idc=useast8&ps=13740610&refresh_token=9a49b526&shcp=9b759fb9&shp=c1333099&t=4d5b0474&x-expires=1793181600&x-signature=F86SkQfx2ZRg%2FBYvwUGHjj3Mytk%3D", "author_id": "6703588751878161413", "author_sec_uid": "MS4wLjABAAAAW3LTNOZ_GjG05TI3Ipw1E9H6A290sDZXI8WuXh3DVr9xDHKGmJCB1PCrWTF6Mpvm", "author_username": "caffeinatedcowgirrl", "author_name": "liv🪶💋⭐️", "author_image_url": "https://p19-common-sign.tiktokcdn-us.com/tos-useast8-avt-0068-tx2/628755574ae284a5ed69f174ea61410b~tplv-tiktokx-cropcenter:1080:1080.webp?dr=9640&refresh_token=bf3381be&x-expires=1793246400&x-signature=bmxWQ04wqXeOSjRVQzHFZq8HBHM%3D&t=4d5b0474&ps=13740610&shp=d05b14bd&shcp=34ff8df6&idc=useast8", "author_verified": null, "author_follower_count": 397918, "view_count": 17357, "like_count": 2245, "comment_count": 20, "share_count": 22, "bookmark_count": 170, "hashtags": [ "coffee", "coffeerecipe", "brownsugarshakenespresso" ], "mentioned_usernames": null, "music_id": "7701495520451152670", "music_title": "original sound - caffeinatedcowgirrl", "music_author_name": "liv🪶💋⭐️" } ], "pagination": { "next_page_token": "pt1.dGlraHViOjIw" } } ```