# List the TikTok videos under a hashtag Returns the TikTok videos posted under a hashtag, with author and date, a page at a time. Use it to see what is posted on a trend. Tool `tiktok.hashtag.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.hashtag.videos/calls \ -H "Authorization: Bearer $VOXORIA_API_KEY" \ -H "Content-Type: application/json" \ -d '{"input":{"hashtag_id":"14104"}}' ``` Python: ```python import os import httpx response = httpx.post( "https://api.voxoria.ai/v1/tools/tiktok.hashtag.videos/calls", headers={"Authorization": f"Bearer {os.environ['VOXORIA_API_KEY']}"}, json={"input": {"hashtag_id": "14104"}}, timeout=60, ) print(response.json()) ``` TypeScript: ```ts const response = await fetch("https://api.voxoria.ai/v1/tools/tiktok.hashtag.videos/calls", { method: "POST", headers: { Authorization: `Bearer ${process.env.VOXORIA_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({"input": {"hashtag_id": "14104"}}), }); console.log(await response.json()); ``` MCP (`tools/call` params): ```json { "name": "call_tool", "arguments": { "tool": "tiktok.hashtag.videos", "input": { "hashtag_id": "14104" } } } ``` 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 | | --- | --- | --- | --- | --- | | `hashtag_id` | string | Yes | | TikTok's numeric identifier of the hashtag. Take it from hashtag.id of tiktok.hashtag.detail. Matches `^[0-9]+$`. | | `next_page_token` | string | No | | Fetches the next page. Take it from pagination.next_page_token of the previous page, and send the same hashtag_id. | ## 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. | | `approx_author_follower_count` | integer | No | Number of the author's followers, approximate, rounded by the source (28.8M is 28800000). | | `approx_view_count` | integer | No | Number of times the video was played, approximate, rounded by the source (33.3M is 33300000). | | `approx_like_count` | integer | No | Number of likes, approximate, rounded by the source (2.1M is 2100000). | | `approx_comment_count` | integer | No | Number of comments, approximate, rounded by the source (12.5K is 12500). | | `approx_share_count` | integer | No | Number of shares, approximate, rounded by the source (12.5K is 12500). | | `approx_bookmark_count` | integer | No | Number of times the video was saved to favorites, approximate, rounded by the source (90.6K is 90600). | | `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": "7083620430933970222", "url": null, "text": "haven’t been able to check-in with y’all in a hot minute 🥺 hope you’re all well 💕 #coffeewithcy #coffee #psl #pumpkinspice #cylovesfrogs #checkin", "published_at": "2022-04-06T22:25:05Z", "duration_ms": 30000, "width": 576, "height": 1024, "preview_image_url": "https://p19-common-sign.tiktokcdn-us.com/tos-useast5-p-0068-tx/0f5886c0658e4bb28de9a204e000ab58_1649283911~tplv-tiktokx-dmt-logom:tos-useast5-p-0000-tx/600721f3b7464b4b88130d4b2fe44476.image?dr=9634&x-expires=1793332800&x-signature=WV9KE9oE96r0mJFOAxT3Z8x%2FqcA%3D&t=4d5b0474&ps=13740610&shp=81f88b70&shcp=43f4a2f9&idc=useast8", "author_id": "6916303262203544581", "author_sec_uid": "MS4wLjABAAAAebBiOuoQhUFn7l-LowI9CaY5kzJ2to2WsG9gmcFl9EoHnKl3oTpjwy_ZB7NmjfBs", "author_username": "cylovesfrogs", "author_name": "Cy Nguyen 🐸", "author_image_url": "https://p16-common-sign.tiktokcdn-us.com/tos-maliva-avt-0068/7328635617629274117~tplv-tiktokx-cropcenter:1080:1080.jpeg?dr=9640&refresh_token=45fd76b0&x-expires=1793332800&x-signature=z7WcBC%2FBSdeRpy%2Fcj%2FndO3SBwGs%3D&t=4d5b0474&ps=13740610&shp=a5d48078&shcp=81f88b70&idc=useast8", "author_verified": false, "author_follower_count": null, "view_count": null, "like_count": null, "comment_count": null, "share_count": null, "bookmark_count": null, "approx_author_follower_count": 1000000, "approx_view_count": 418900, "approx_like_count": 54800, "approx_comment_count": 549, "approx_share_count": 278, "approx_bookmark_count": 2006, "hashtags": [ "coffeewithcy", "coffee", "psl" ], "mentioned_usernames": null, "music_id": "6763548081012082689", "music_title": "Fall Sounds", "music_author_name": "Ori" }, { "id": "7083220201453489414", "url": null, "text": "Reply to @ochaplant some Pourover coffee tips! #coffeetok #pourovercoffee #coffee", "published_at": "2022-04-05T20:32:00Z", "duration_ms": 55000, "width": 576, "height": 1024, "preview_image_url": "https://p19-common-sign.tiktokcdn-us.com/tos-maliva-p-0068/c5a5a3be787348699024d3185c1bef89_1649190724~tplv-tiktokx-dmt-logom:tos-useast2a-v-0068/23c7d5eb899b415fac10c84c72cf4cfc.image?dr=9634&x-expires=1793332800&x-signature=bahWYRYkZ%2BZnt8MX7e%2FKgiHJ41M%3D&t=4d5b0474&ps=13740610&shp=81f88b70&shcp=43f4a2f9&idc=useast8", "author_id": "6804087606605267974", "author_sec_uid": "MS4wLjABAAAAF3-gBuFmyG_sdTC9CSIuRxzvAIjHqwajSyYKa_5y0Qfwsor0qlWncUzvwGEduVwu", "author_username": "cc.campbell", "author_name": "Caitlin.Campbell", "author_image_url": "https://p16-common-sign.tiktokcdn-us.com/tos-maliva-avt-0068/cfbfcf79005d73603d46e85c044c13b2~tplv-tiktokx-cropcenter:1080:1080.jpeg?dr=9640&refresh_token=3d7f0bdd&x-expires=1793332800&x-signature=LNOQrHjjCKoF21tpIFhpqgtXEcw%3D&t=4d5b0474&ps=13740610&shp=a5d48078&shcp=81f88b70&idc=useast8", "author_verified": true, "author_follower_count": null, "view_count": null, "like_count": null, "comment_count": null, "share_count": null, "bookmark_count": null, "approx_author_follower_count": 1300000, "approx_view_count": 245100, "approx_like_count": 15300, "approx_comment_count": 229, "approx_share_count": 257, "approx_bookmark_count": 1160, "hashtags": [ "coffeetok", "pourovercoffee", "coffee" ], "mentioned_usernames": [ "ochaplant" ], "music_id": "6953851540646709249", "music_title": "A-O-K", "music_author_name": "Tai Verdes" }, { "id": "7084896024384392449", "url": null, "text": "Latte art from @flat_white_short_film #fyp #latteart #shortfilm #flatwhite", "published_at": "2022-04-10T08:55:04Z", "duration_ms": 31000, "width": 576, "height": 1024, "preview_image_url": "https://p19-common-sign.tiktokcdn-us.com/tos-alisg-p-0037/36b701f8c3144faab58731d02892903f~tplv-tiktokx-origin.image?dr=9636&x-expires=1793332800&x-signature=R5bxwWTvwIcXHNmpaS3VNAs7HSU%3D&t=4d5b0474&ps=13740610&shp=81f88b70&shcp=43f4a2f9&idc=useast8", "author_id": "6985821148056110082", "author_sec_uid": "MS4wLjABAAAAgFOhQQHCPrkuJK6WgcxAbElnVvFRLTRPUtDC3hiE1lojDxgvb4PEdZ9Plqz6QADq", "author_username": "annie_jordan", "author_name": "Annie Jordan", "author_image_url": "https://p16-common-sign.tiktokcdn-us.com/tos-alisg-avt-0068/c642ea00d247f760790f100339153ac8~tplv-tiktokx-cropcenter:1080:1080.jpeg?dr=9640&refresh_token=901833ed&x-expires=1793332800&x-signature=rU6BhHMilnvqQ6sNysXmcU53lbU%3D&t=4d5b0474&ps=13740610&shp=a5d48078&shcp=81f88b70&idc=useast8", "author_verified": false, "author_follower_count": null, "view_count": null, "like_count": null, "comment_count": null, "share_count": null, "bookmark_count": null, "approx_author_follower_count": 22400, "approx_view_count": 37700000, "approx_like_count": 4200000, "approx_comment_count": 9341, "approx_share_count": 33300, "approx_bookmark_count": 72400, "hashtags": [ "fyp", "latteart", "shortfilm" ], "mentioned_usernames": [ "flat_white_short_film" ], "music_id": "7026792865289029633", "music_title": "Material Girl (Bass Boosted)", "music_author_name": "Saucy Santana" } ], "pagination": { "next_page_token": "pt1.dGlraHViOjQ1" } } ```