> ## Documentation Index > Fetch the complete documentation index at: https://docs.sideshift.app/llms.txt > Use this file to discover all available pages before exploring further. # TikTok and Instagram platform operations > 42 focused operations with clean platform/resource paths and documented platform response fields. Use these operations when you need platform-specific data beyond the normalized `profile`, `posts`, `post`, and TikTok `audience` resources. Start with a [normalized endpoint](/scraper/platforms) when it covers your use case. It gives you the same response schema across platforms. Choose an operation on this page when you need a platform-only resource or the platform's full field structure. ## Choose an operation | Need | Use | | ---------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | | Comparable profiles or posts across platforms | [Normalized endpoints](/scraper/platforms) | | TikTok favorites, reposts, stories, social graph, sounds, hashtags, playlists, search, trends, comments, transcripts, or ads | A TikTok operation below | | Instagram timeline, reels, full post details, comments, search, audio, or highlights | An Instagram operation below | | Exact request and response schemas | The [API reference](#api-reference) or an endpoint in the left navigation | Every public path follows one convention: ```text theme={"system"} POST https://app.sideshift.app/api/v1/scrape/{platform}/{resource} ``` Overlapping capabilities are combined only when their request and response contracts are compatible. Rich profile objects, Instagram timelines and reels, and full Instagram post objects have explicit operation names because replacing the normalized response schema would break existing integrations. TikTok audience sampling is consolidated into the normalized `/tiktok/audience` route because its response remains wire-compatible. The `data` object in every interactive `200` example was captured from a successful live request on **2026-08-07** using the request body shown for that operation. To keep the reference readable and safe, arrays show representative items, long strings are trimmed, public contact fields are redacted, and transient URL query strings are removed. SideShift applies the same authentication, billing, error, and outer response envelope to every operation. ## Quick example Send a SideShift scraper key (`scrape_live_*`) in the `x-api-key` header and a JSON request body. See the [quickstart](/scraper/quickstart) for complete setup examples. ```bash theme={"system"} export SIDESHIFT_SCRAPER_KEY="scrape_live_YOUR_KEY" curl -X POST https://app.sideshift.app/api/v1/scrape/tiktok/profile-details \ -H "x-api-key: $SIDESHIFT_SCRAPER_KEY" \ -H "Content-Type: application/json" \ -d '{"handle":"tiktok"}' ``` ## Response shape The operation examples below document the contents of `data`. The outer envelope is consistent across the entire Scraper API: ```json theme={"system"} { "data": { "itemList": [], "stats": { "diggCount": null, "followerCount": 95150665, "followingCount": 0, "heart": 462526742, "heartCount": 462526742, "videoCount": 1570 }, "user": { "UserStoryStatus": 0, "avatarLarger": "https://p19-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/ba67b11de451691939223e9d978e613a~tplv-tiktokx-cropcenter:1080:1080.webp", "avatarMedium": "https://p19-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/ba67b11de451691939223e9d978e613a~tplv-tiktokx-cropcenter:720:720.webp", "avatarThumb": "https://p19-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/ba67b11de451691939223e9d978e613a~tplv-tiktokx-cropcenter:100:100.webp", "commentSetting": null, "createTime": 1425144149, "duetSetting": null, "ftc": false, "id": "107955", "ins_id": "", "isADVirtual": false, "isUnderAge18": false, "nickname": "TikTok", "openFavorite": false, "privateAccount": false, "relation": 0, "secUid": "MS4wLjABAAAAv7iSuuXDJGDvJkmH_vz1qkDZYo1apxgzaxdBSeIuPiM", "secret": false, "signature": "One TikTok can make a big impac", "stitchSetting": null, "twitter_id": "", "uniqueId": "tiktok", "verified": true, "youtube_channel_id": "", "youtube_channel_title": "", "bioLink": { "link": "linktr.ee/tiktok" } } }, "request_id": "req_8f3c9a2b1d4e6f70", "upstream_calls": 1, "meta": { "credits_charged": 1, "credits_remaining": 9999 } } ``` Platform field names and nesting inside `data` are intentionally preserved. Keep the capitalization shown in the schemas, including `uniqueId`, `UserStoryStatus`, `strong_id__`, and `AIGCDescription`. A missing count can be `null`; numeric `0` means the platform returned a real zero. Read [Responses and data](/scraper/responses) for the envelope, identifier, media URL, and nullability rules. ## Billing, pagination, and failures * Every completed platform operation or page costs **1 SideShift credit**. * Confirmed not-found responses are billed. * Requests rejected before work starts (`400`, `401`, `402`, `413`, `429`) are free. * SideShift/data-source failures and timeouts (`500`, `502`, `504`) are refunded. Pass returned cursors back verbatim and stop when the corresponding `has_more` flag is false. TikTok follower/following lists use `min_time`; collection posts use `max_cursor`; Instagram timeline uses `next_max_id`; Instagram reels use `max_id`; and Instagram hashtag/profile search uses page numbers capped at 10. Single-shot operations return no cursor. Read `meta.credits_charged` on success and `X-Scraper-Credits-Charged` on errors. Retry refunded `500`/`502`/`504` failures with backoff, do not loop on billed `404` responses, and honor `Retry-After` on `429`. See [Billing, errors, and limits](/scraper/billing-and-limits) for the complete policy and a copyable retry wrapper. ## API reference The operation sections below include copyable requests, parameter tables, pagination rules, and response-field tables. The left navigation also exposes a generated interactive reference for every endpoint. *** # TikTok — 27 platform operations Posts come back as TikTok's `aweme` object: `aweme_id` (the numeric id in a permalink), `desc`, `statistics` (`play_count`, `digg_count`, `comment_count`, `share_count`, `collect_count`), `video` (`play_addr`, `cover`, `duration` — each URL field is a `{uri, url_list}` wrapper, read `url_list[0]`), `author`, `music`, `create_time` and `url`. Creators come back as `uid` / `unique_id` / `nickname` / `sec_uid` / `avatar_medium` / `follower_count` / `following_count`. ## TikTok · Creator ### `POST /api/v1/scrape/tiktok/profile-details` Profile header for one creator — identity, counts, links. | Field | Type | Required | Default | Description | | --------------------------- | ---- | -------- | ------- | ----------------------------------------------------- | | `handle` *(or `unique_id`)* | str | no | `null` | Creator's username/handle (with or without @). | | `user_id` | str | no | `null` | Numeric TikTok user id — an alternative to unique\_id | | `cache_max_age` | str | no | `null` | Accepted and ignored — every response is a live read. | ```bash theme={"system"} curl -X POST https://app.sideshift.app/api/v1/scrape/tiktok/profile-details \ -H 'x-api-key: $SIDESHIFT_SCRAPER_KEY' -H 'Content-Type: application/json' \ -d '{"handle": "tiktok"}' ``` > Returns `user` and `stats` in TikTok's own web shape. `itemList` is present and empty; use the post endpoints for a feed. **Response** — the `data` object: | Key | Type | | | ---------- | ------ | - | | `user` | object | | | `stats` | object | | | `itemList` | array | | ```json theme={"system"} { "itemList": [], "stats": { "diggCount": null, "followerCount": 95150665, "followingCount": 0, "heart": 462526742, "heartCount": 462526742, "videoCount": 1570 }, "user": { "UserStoryStatus": 0, "avatarLarger": "https://p19-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/ba67b11de451691939223e9d978e613a~tplv-tiktokx-cropcenter:1080:1080.webp", "avatarMedium": "https://p19-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/ba67b11de451691939223e9d978e613a~tplv-tiktokx-cropcenter:720:720.webp", "avatarThumb": "https://p19-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/ba67b11de451691939223e9d978e613a~tplv-tiktokx-cropcenter:100:100.webp", "commentSetting": null, "createTime": 1425144149, "duetSetting": null, "ftc": false, "id": "107955", "ins_id": "", "isADVirtual": false, "isUnderAge18": false, "nickname": "TikTok", "openFavorite": false, "privateAccount": false, "relation": 0, "secUid": "MS4wLjABAAAAv7iSuuXDJGDvJkmH_vz1qkDZYo1apxgzaxdBSeIuPiM", "secret": false, "signature": "One TikTok can make a big impac", "stitchSetting": null, "twitter_id": "", "uniqueId": "tiktok", "verified": true, "youtube_channel_id": "", "youtube_channel_title": "", "bioLink": { "link": "linktr.ee/tiktok" } } } ``` `user` fields: | Field | Type | Example | | ----------------------- | ------- | ----------------------------------------- | | `id` | string | `"107955"` | | `uniqueId` | string | `"tiktok"` | | `nickname` | string | `"TikTok"` | | `avatarThumb` | string | `"https://p16-common-sign.tiktokcdn-us.…` | | `avatarMedium` | string | `"https://p16-common-sign.tiktokcdn-us.…` | | `avatarLarger` | string | `"https://p19-common-sign.tiktokcdn-us.…` | | `signature` | string | `"One TikTok can make a big impact"` | | `verified` | boolean | `true` | | `secUid` | string | `"MS4wLjABAAAAv7iSuuXDJGDvJkmH_vz1qkDZY…` | | `secret` | boolean | `false` | | `ftc` | boolean | `false` | | `relation` | number | `0` | | `openFavorite` | boolean | `false` | | `commentSetting` | null | | | `duetSetting` | null | | | `stitchSetting` | null | | | `privateAccount` | boolean | `false` | | `isADVirtual` | boolean | `false` | | `isUnderAge18` | boolean | `false` | | `ins_id` | string | | | `twitter_id` | string | | | `youtube_channel_title` | string | | | `youtube_channel_id` | string | | | `UserStoryStatus` | number | `0` | | `createTime` | number | `1425144149` | | `bioLink` | object | nested: `link` | `stats` fields: | Field | Type | Example | | ---------------- | ------ | ----------- | | `followingCount` | number | `0` | | `followerCount` | number | `95148223` | | `heartCount` | number | `462523908` | | `videoCount` | number | `1570` | | `diggCount` | null | | | `heart` | number | `462523908` | ### `POST /api/v1/scrape/tiktok/favorites` Videos a creator publicly liked. | Field | Type | Required | Default | Description | | --------------------------- | ---- | -------- | ------- | -------------------------------------------------------------------------------------------------- | | `handle` *(or `unique_id`)* | str | no | `null` | Creator's username/handle (with or without @). | | `user_id` | str | no | `null` | Numeric TikTok user id — an alternative to unique\_id | | `cursor` | str | no | `'0'` | Pagination cursor — echo back the `cursor` from the previous response. Omit it for the first page. | ```bash theme={"system"} curl -X POST https://app.sideshift.app/api/v1/scrape/tiktok/favorites \ -H 'x-api-key: $SIDESHIFT_SCRAPER_KEY' -H 'Content-Type: application/json' \ -d '{"handle": "ramiryatebyalybly", "cursor": "0"}' ``` > Most accounts hide their Liked tab, so an empty page is normal rather than an error. **Response** — the `data` object: | Key | Type | | | ------------ | --------------- | -------------------------------------------------------------- | | `aweme_list` | array of `post` | | | `cursor` | string | Pass back on the next call. `null` once the list is exhausted. | | `has_more` | boolean | Whether another page exists. | | `unique_id` | string | Echo of what you queried. | | `user_id` | null | Echo of what you queried. | ```json theme={"system"} { "cursor": "1781353841000000", "has_more": true, "unique_id": "ramiryatebyalybly", "user_id": null, "aweme_list": [ { "anchors": null, "author_user_id": "6759815698284053509", "aweme_id": "7669066355013930260", "aweme_type": 0, "create_time": 1785593661, "create_time_utc": "2026-08-01T14:14:21.000Z", "desc": null, "desc_language": null, "image_post_info": null, "is_ad": false, "is_eligible_for_commission": null, "is_nff_or_nr": false, "is_paid_partnership": null, "is_top": 0, "item_comment_settings": 0, "media_id": "v14044g50000d9mvu3fog65p6mu31mj0", "region": "CH", "shop_product_url": null, "url": "https://www.tiktok.com/@ira_sorokina042/video/7669066355013930260", "author": { "events": null, "language": null, "nickname": "Ирина", "region": "CH", "sec_uid": null, "short_id": null, "signature": null, "social_info": null, "uid": "6759815698284053509", "unique_id": "ira_sorokina042", "avatar_larger": { "height": null, "uri": "https://p16-common-sign.tiktokcdn-us.com/tos-alisg-avt-0068/021a8fe76dc2584492de373000102165~tplv-tiktokx-cropcenter-q:300:300:q70.jpeg", "url_prefix": null, "width": null, "url_list": [ "https://p16-common-sign.tiktokcdn-us.com/tos-alisg-avt-0068/021a8fe76dc2584492de373000102165~tplv-tiktokx-cropcenter-q:300:300:q70.jpeg" ] }, "avatar_medium": { "height": null, "uri": "https://p16-common-sign.tiktokcdn-us.com/tos-alisg-avt-0068/021a8fe76dc2584492de373000102165~tplv-tiktokx-cropcenter-q:300:300:q70.jpeg", "url_prefix": null, "width": null, "url_list": [ "https://p16-common-sign.tiktokcdn-us.com/tos-alisg-avt-0068/021a8fe76dc2584492de373000102165~tplv-tiktokx-cropcenter-q:300:300:q70.jpeg" ] }, "avatar_thumb": { "height": null, "uri": "https://p16-common-sign.tiktokcdn-us.com/tos-alisg-avt-0068/021a8fe76dc2584492de373000102165~tplv-tiktokx-cropcenter-q:300:300:q70.jpeg", "url_prefix": null, "width": null, "url_list": [ "https://p16-common-sign.tiktokcdn-us.com/tos-alisg-avt-0068/021a8fe76dc2584492de373000102165~tplv-tiktokx-cropcenter-q:300:300:q70.jpeg" ] } }, "commerce_info": { "adv_promotable": false, "auction_ad_invited": false, "branded_content_type": 0, "is_diversion_ad": 0, "organic_log_extra": "{\"req_id\":\"2026080723113813965DB9DAE29E4CF8E0\"}", "with_comment_filter_words": false }, "music": { "album": null, "author": "__MELOMANIA__", "duration": 50, "id": "7042668177377463042", "id_str": "7042668177377463042", "is_original": true, "is_original_sound": true, "mid": "7042668177377463042", "owner_nickname": "__MELOMANIA__", "title": "original sound - _melomania74_", "user_count": null, "cover_large": { "height": null, "uri": "https://p19-common-sign.tiktokcdn-us.com/tos-alisg-avt-0068/0800b192aed28e9a18fcc8123d3f25f4~tplv-tiktokx-cropcenter-q:1080:1080:q70.jpeg", "url_prefix": null, "width": null, "url_list": [ "https://p19-common-sign.tiktokcdn-us.com/tos-alisg-avt-0068/0800b192aed28e9a18fcc8123d3f25f4~tplv-tiktokx-cropcenter-q:1080:1080:q70.jpeg" ] }, "cover_medium": { "height": null, "uri": "https://p19-common-sign.tiktokcdn-us.com/tos-alisg-avt-0068/0800b192aed28e9a18fcc8123d3f25f4~tplv-tiktokx-cropcenter-q:1080:1080:q70.jpeg", "url_prefix": null, "width": null, "url_list": [ "https://p19-common-sign.tiktokcdn-us.com/tos-alisg-avt-0068/0800b192aed28e9a18fcc8123d3f25f4~tplv-tiktokx-cropcenter-q:1080:1080:q70.jpeg" ] }, "cover_thumb": { "height": null, "uri": "https://p19-common-sign.tiktokcdn-us.com/tos-alisg-avt-0068/0800b192aed28e9a18fcc8123d3f25f4~tplv-tiktokx-cropcenter-q:1080:1080:q70.jpeg", "url_prefix": null, "width": null, "url_list": [ "https://p19-common-sign.tiktokcdn-us.com/tos-alisg-avt-0068/0800b192aed28e9a18fcc8123d3f25f4~tplv-tiktokx-cropcenter-q:1080:1080:q70.jpeg" ] } }, "statistics": { "aweme_id": "7669066355013930260", "collect_count": 398, "comment_count": 16, "digg_count": 5078, "download_count": 90, "forward_count": null, "lose_comment_count": null, "lose_count": null, "play_count": 74676, "repost_count": null, "share_count": 1812, "whatsapp_share_count": null }, "video": { "data_size": 456017, "duration": null, "height": null, "watermark_data_size": 480697, "width": null, "cover": { "height": null, "uri": "https://p19-common-sign.tiktokcdn-us.com/tos-alisg-p-0037/oQAdR1kfjUEtDoDYEoDbb8FfAz22AA9I8XfAQI~tplv-tiktokx-cropcenter-q:300:400:q70.jpeg", "url_prefix": null, "width": null, "url_list": [ "https://p19-common-sign.tiktokcdn-us.com/tos-alisg-p-0037/oQAdR1kfjUEtDoDYEoDbb8FfAz22AA9I8XfAQI~tplv-tiktokx-cropcenter-q:300:400:q70.jpeg" ] }, "download_addr": { "height": null, "uri": "https://v16m.tiktokcdn-us.com/d198eda0aef2f5fb5deff77be109ab18/6a76ba90/video/tos/alisg/tos-alisg-pve-0037c001/ok88QoMaNDA4f3qX3fFyDjUOLIhAtCs2IhfhbE/", "url_prefix": null, "width": null, "url_list": [ "https://v16m.tiktokcdn-us.com/d198eda0aef2f5fb5deff77be109ab18/6a76ba90/video/tos/alisg/tos-alisg-pve-0037c001/ok88QoMaNDA4f3qX3fFyDjUOLIhAtCs2IhfhbE/" ] }, "dynamic_cover": { "height": null, "uri": "https://p16-common-sign.tiktokcdn-us.com/tos-alisg-p-0037/oQAdR1kfjUEtDoDYEoDbb8FfAz22AA9I8XfAQI~tplv-tiktokx-origin.image", "url_prefix": null, "width": null, "url_list": [ "https://p16-common-sign.tiktokcdn-us.com/tos-alisg-p-0037/oQAdR1kfjUEtDoDYEoDbb8FfAz22AA9I8XfAQI~tplv-tiktokx-origin.image" ] }, "origin_cover": { "height": null, "uri": "https://p19-common-sign.tiktokcdn-us.com/tos-alisg-p-0037/ooQIh7F2tQDGNyCA8MHAf3EaUbQGjdhDoK0ffC~tplv-tiktokx-shrink-aq:360:360:q75.jpeg", "url_prefix": null, "width": null, "url_list": [ "https://p19-common-sign.tiktokcdn-us.com/tos-alisg-p-0037/ooQIh7F2tQDGNyCA8MHAf3EaUbQGjdhDoK0ffC~tplv-tiktokx-shrink-aq:360:360:q75.jpeg" ] }, "play_addr": { "height": null, "uri": "https://v16m.tiktokcdn-us.com/7ec2e05aedf1cc25a3a328b6380ee0d7/6a76ba90/video/tos/alisg/tos-alisg-pve-0037c001/oc6ffF8kA0hjJDytIMfDNaqhLiEI2UpoANCbQ3/", "url_prefix": null, "width": null, "url_list": [ "https://v16m.tiktokcdn-us.com/7ec2e05aedf1cc25a3a328b6380ee0d7/6a76ba90/video/tos/alisg/tos-alisg-pve-0037c001/oc6ffF8kA0hjJDytIMfDNaqhLiEI2UpoANCbQ3/" ] } } } ] } ``` ### `POST /api/v1/scrape/tiktok/reposts` Posts a creator reposted. | Field | Type | Required | Default | Description | | --------------------------- | ---- | -------- | ------- | -------------------------------------------------------------------------------------------------- | | `handle` *(or `unique_id`)* | str | no | `null` | Creator's username/handle (with or without @). | | `user_id` | str | no | `null` | Numeric TikTok user id — an alternative to unique\_id | | `cursor` | str | no | `'0'` | Pagination cursor — echo back the `cursor` from the previous response. Omit it for the first page. | ```bash theme={"system"} curl -X POST https://app.sideshift.app/api/v1/scrape/tiktok/reposts \ -H 'x-api-key: $SIDESHIFT_SCRAPER_KEY' -H 'Content-Type: application/json' \ -d '{"handle": "tiktok", "cursor": "0"}' ``` > Each item is the ORIGINAL author's post, so `author.unique_id` is that author, not the account queried. **Response** — the `data` object: | Key | Type | | | ------------ | --------------- | -------------------------------------------------------------- | | `aweme_list` | array of `post` | | | `cursor` | string | Pass back on the next call. `null` once the list is exhausted. | | `has_more` | boolean | Whether another page exists. | | `unique_id` | string | Echo of what you queried. | | `user_id` | null | Echo of what you queried. | ```json theme={"system"} { "cursor": "30", "has_more": true, "unique_id": "tiktok", "user_id": null, "aweme_list": [ { "anchors": null, "author_user_id": "292342703596507136", "aweme_id": "7671088500850101534", "aweme_type": 0, "create_time": 1786064480, "create_time_utc": "2026-08-07T01:01:20.000Z", "desc": "AND ITS LIVE ON @TikTok and @iHeartRadio IN 1 HOUR", "desc_language": null, "image_post_info": null, "is_ad": false, "is_eligible_for_commission": null, "is_nff_or_nr": false, "is_paid_partnership": null, "is_top": 0, "item_comment_settings": 0, "media_id": "v15044gf0000d9qio3vog65i02gotgig", "region": "US", "shop_product_url": null, "url": "https://www.tiktok.com/@alexwarren/video/7671088500850101534", "author": { "events": null, "language": null, "nickname": "Alex Warren", "region": "US", "sec_uid": null, "short_id": null, "signature": null, "social_info": null, "uid": "292342703596507136", "unique_id": "alexwarren", "avatar_larger": { "height": null, "uri": "https://p19-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/e55faf9f219550b3b75f6dbf64a7717f~tplv-tiktokx-cropcenter:300:300.jpeg", "url_prefix": null, "width": null, "url_list": [ "https://p19-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/e55faf9f219550b3b75f6dbf64a7717f~tplv-tiktokx-cropcenter:300:300.jpeg" ] }, "avatar_medium": { "height": null, "uri": "https://p19-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/e55faf9f219550b3b75f6dbf64a7717f~tplv-tiktokx-cropcenter:300:300.jpeg", "url_prefix": null, "width": null, "url_list": [ "https://p19-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/e55faf9f219550b3b75f6dbf64a7717f~tplv-tiktokx-cropcenter:300:300.jpeg" ] }, "avatar_thumb": { "height": null, "uri": "https://p19-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/e55faf9f219550b3b75f6dbf64a7717f~tplv-tiktokx-cropcenter:300:300.jpeg", "url_prefix": null, "width": null, "url_list": [ "https://p19-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/e55faf9f219550b3b75f6dbf64a7717f~tplv-tiktokx-cropcenter:300:300.jpeg" ] } }, "commerce_info": { "adv_promotable": false, "auction_ad_invited": false, "branded_content_type": 0, "is_diversion_ad": 0, "organic_log_extra": "{\"req_id\":\"20260807231141A33ECE668573E13C65D8\"}", "with_comment_filter_words": false }, "music": { "album": null, "author": "Alex Warren", "duration": 18, "id": "7667300537578801950", "id_str": "7667300537578801950", "is_original": true, "is_original_sound": true, "mid": "7667300537578801950", "owner_nickname": "Alex Warren", "title": "RESCUER BRIDGE", "user_count": null, "cover_large": { "height": null, "uri": "https://p16-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/e55faf9f219550b3b75f6dbf64a7717f~tplv-tiktokx-cropcenter:1080:1080.jpeg", "url_prefix": null, "width": null, "url_list": [ "https://p16-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/e55faf9f219550b3b75f6dbf64a7717f~tplv-tiktokx-cropcenter:1080:1080.jpeg" ] }, "cover_medium": { "height": null, "uri": "https://p16-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/e55faf9f219550b3b75f6dbf64a7717f~tplv-tiktokx-cropcenter:1080:1080.jpeg", "url_prefix": null, "width": null, "url_list": [ "https://p16-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/e55faf9f219550b3b75f6dbf64a7717f~tplv-tiktokx-cropcenter:1080:1080.jpeg" ] }, "cover_thumb": { "height": null, "uri": "https://p16-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/e55faf9f219550b3b75f6dbf64a7717f~tplv-tiktokx-cropcenter:1080:1080.jpeg", "url_prefix": null, "width": null, "url_list": [ "https://p16-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/e55faf9f219550b3b75f6dbf64a7717f~tplv-tiktokx-cropcenter:1080:1080.jpeg" ] } }, "statistics": { "aweme_id": "7671088500850101534", "collect_count": 5162, "comment_count": 1708, "digg_count": 107894, "download_count": 90, "forward_count": null, "lose_comment_count": null, "lose_count": null, "play_count": 1203738, "repost_count": null, "share_count": 1371, "whatsapp_share_count": null }, "video": { "data_size": 2129659, "duration": 9, "height": null, "watermark_data_size": 1953959, "width": null, "cover": { "height": null, "uri": "https://p19-common-sign.tiktokcdn-us.com/tos-useast8-p-0068-tx2/oIDZ1lfyAV6lUFAIpn4EAeqQE6IILEeAjIBA66~tplv-tiktokx-cropcenter-q:300:400:q70.jpeg", "url_prefix": null, "width": null, "url_list": [ "https://p19-common-sign.tiktokcdn-us.com/tos-useast8-p-0068-tx2/oIDZ1lfyAV6lUFAIpn4EAeqQE6IILEeAjIBA66~tplv-tiktokx-cropcenter-q:300:400:q70.jpeg" ] }, "download_addr": { "height": null, "uri": "https://v45.tiktokcdn-us.com/9b94166b167124eea8ce72e6901ff5d6/6a76ba96/video/tos/useast8/tos-useast8-pve-0068-tx2/o4lIyOiRGBA0u1qmCKYHLlAIBfAbiiQwOA31pE/", "url_prefix": null, "width": null, "url_list": [ "https://v45.tiktokcdn-us.com/9b94166b167124eea8ce72e6901ff5d6/6a76ba96/video/tos/useast8/tos-useast8-pve-0068-tx2/o4lIyOiRGBA0u1qmCKYHLlAIBfAbiiQwOA31pE/" ] }, "dynamic_cover": { "height": null, "uri": "https://p19-common-sign.tiktokcdn-us.com/tos-useast8-p-0068-tx2/oIDZ1lfyAV6lUFAIpn4EAeqQE6IILEeAjIBA66~tplv-tiktokx-origin.image", "url_prefix": null, "width": null, "url_list": [ "https://p19-common-sign.tiktokcdn-us.com/tos-useast8-p-0068-tx2/oIDZ1lfyAV6lUFAIpn4EAeqQE6IILEeAjIBA66~tplv-tiktokx-origin.image" ] }, "origin_cover": { "height": null, "uri": "https://p19-common-sign.tiktokcdn-us.com/tos-useast8-p-0068-tx2/oMmp4BOAIAqHAwBCyiLijOYGPIJIAJiG11AKlf~tplv-tiktokx-shrink-aq:360:360:q75.webp", "url_prefix": null, "width": null, "url_list": [ "https://p19-common-sign.tiktokcdn-us.com/tos-useast8-p-0068-tx2/oMmp4BOAIAqHAwBCyiLijOYGPIJIAJiG11AKlf~tplv-tiktokx-shrink-aq:360:360:q75.webp" ] }, "play_addr": { "height": null, "uri": "https://v45.tiktokcdn-us.com/8a31c1a2843410be8894c0b781fff575/6a76ba96/video/tos/useast8/tos-useast8-pve-0068-tx2/owIzwIA1LO1LYiOxyl9BmAQCqwifAHABGECKip/", "url_prefix": null, "width": null, "url_list": [ "https://v45.tiktokcdn-us.com/8a31c1a2843410be8894c0b781fff575/6a76ba96/video/tos/useast8/tos-useast8-pve-0068-tx2/owIzwIA1LO1LYiOxyl9BmAQCqwifAHABGECKip/" ] } } } ] } ``` ### `POST /api/v1/scrape/tiktok/stories` A creator's currently-live stories (they expire after 24h). | Field | Type | Required | Default | Description | | --------------------------- | ---- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | `handle` *(or `unique_id`)* | str | no | `null` | Creator's username/handle — resolved to a user id for you. Pass `user_id` directly when you have it to skip the lookup. | | `user_id` | str | no | `null` | Numeric TikTok user id | | `cursor` | str | no | `'0'` | Pagination cursor — echo back the `cursor` from the previous response. Omit it for the first page.. Creators with many live stories span several pages. | ```bash theme={"system"} curl -X POST https://app.sideshift.app/api/v1/scrape/tiktok/stories \ -H 'x-api-key: $SIDESHIFT_SCRAPER_KEY' -H 'Content-Type: application/json' \ -d '{"user_id": "107955", "cursor": "0"}' ``` > Stories expire after 24 hours and most creators do not post them, so an empty `aweme_list` is the normal answer and means "no live story right now" — not an error, and not an empty account. **Response** — the `data` object: | Key | Type | | | ------------ | --------------- | -------------------------------------------------------------- | | `aweme_list` | array of `post` | | | `cursor` | null | Pass back on the next call. `null` once the list is exhausted. | | `has_more` | boolean | Whether another page exists. | | `unique_id` | null | Echo of what you queried. | | `user_id` | string | Echo of what you queried. | ```json theme={"system"} { "cursor": null, "has_more": false, "unique_id": null, "user_id": "107955", "aweme_list": [] } ``` ### `POST /api/v1/scrape/tiktok/followers` Accounts following a creator. | Field | Type | Required | Default | Description | | --------------------------- | ---- | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------- | | `handle` *(or `unique_id`)* | str | no | `null` | Creator's username/handle — resolved to a user id for you. Pass `user_id` directly when you have it to skip the lookup. | | `user_id` | str | no | `null` | Numeric TikTok user id | | `min_time` *(or `cursor`)* | str | no | `'0'` | Pagination cursor — echo back the `min_time` from the previous response. | | `trim` | bool | no | `False` | Accepted and ignored — the full object is always returned. | ```bash theme={"system"} curl -X POST https://app.sideshift.app/api/v1/scrape/tiktok/followers \ -H 'x-api-key: $SIDESHIFT_SCRAPER_KEY' -H 'Content-Type: application/json' \ -d '{"handle": "tiktok"}' ``` > Pages on `min_time`, not `cursor`. `total` carries the real follower count, so the gap between it and what pagination reaches is always visible. **Response** — the `data` object: | Key | Type | | | ----------- | ------------------ | ---------------------------------------------------------- | | `followers` | array of `creator` | | | `min_time` | string | Pagination cursor for this surface. `null` once exhausted. | | `has_more` | boolean | Whether another page exists. | | `total` | number | Total across the whole list, not just this page. | | `unique_id` | string | Echo of what you queried. | | `user_id` | string | Echo of what you queried. | ```json theme={"system"} { "has_more": true, "min_time": "1786144180", "total": 95152527, "unique_id": "tiktok", "user_id": "107955", "followers": [ { "aweme_count": 4, "create_time": null, "favoriting_count": 1296, "follower_count": 9, "following_count": 163, "language": null, "nickname": "Lily", "region": "US", "sec_uid": "MS4wLjABAAAAtRZtedn0M_PNRVqjbZN8mgo4sqp63--pgVGV0Ji-Zxe7eMtPIDiO1Cl1cGHve6YE", "secret": false, "signature": null, "total_favorited": 100, "uid": "7669208390450709517", "unique_id": "lilianhamendez4", "verified": false, "avatar_larger": { "height": null, "uri": "https://p16-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/b284745ea53e91c375034e1c26f35bb9~tplv-tiktokx-cropcenter:300:300.jpeg", "url_prefix": null, "width": null, "url_list": [ "https://p16-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/b284745ea53e91c375034e1c26f35bb9~tplv-tiktokx-cropcenter:300:300.jpeg" ] }, "avatar_medium": { "height": null, "uri": "https://p16-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/b284745ea53e91c375034e1c26f35bb9~tplv-tiktokx-cropcenter:300:300.jpeg", "url_prefix": null, "width": null, "url_list": [ "https://p16-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/b284745ea53e91c375034e1c26f35bb9~tplv-tiktokx-cropcenter:300:300.jpeg" ] }, "avatar_thumb": { "height": null, "uri": "https://p16-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/b284745ea53e91c375034e1c26f35bb9~tplv-tiktokx-cropcenter:300:300.jpeg", "url_prefix": null, "width": null, "url_list": [ "https://p16-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/b284745ea53e91c375034e1c26f35bb9~tplv-tiktokx-cropcenter:300:300.jpeg" ] } } ] } ``` ### `POST /api/v1/scrape/tiktok/following` Accounts a creator follows. | Field | Type | Required | Default | Description | | --------------------------- | ---- | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------- | | `handle` *(or `unique_id`)* | str | no | `null` | Creator's username/handle — resolved to a user id for you. Pass `user_id` directly when you have it to skip the lookup. | | `user_id` | str | no | `null` | Numeric TikTok user id | | `min_time` *(or `cursor`)* | str | no | `'0'` | Pagination cursor — echo back the `min_time` from the previous response. | | `trim` | bool | no | `False` | Accepted and ignored — the full object is always returned. | ```bash theme={"system"} curl -X POST https://app.sideshift.app/api/v1/scrape/tiktok/following \ -H 'x-api-key: $SIDESHIFT_SCRAPER_KEY' -H 'Content-Type: application/json' \ -d '{"handle": "tiktok"}' ``` > Pages on `min_time`. Empty for accounts that hide the list. **Response** — the `data` object: | Key | Type | | | ------------ | ------------------ | ---------------------------------------------------------- | | `followings` | array of `creator` | | | `min_time` | null | Pagination cursor for this surface. `null` once exhausted. | | `has_more` | boolean | Whether another page exists. | | `total` | number | Total across the whole list, not just this page. | | `unique_id` | string | Echo of what you queried. | | `user_id` | string | Echo of what you queried. | ```json theme={"system"} { "has_more": false, "min_time": null, "total": 2, "unique_id": "tiktok", "user_id": "107955", "followings": [ { "aweme_count": 1096, "create_time": null, "favoriting_count": 1865, "follower_count": 8609888, "following_count": 569, "language": null, "nickname": "tiktok creators", "region": "US", "sec_uid": "MS4wLjABAAAAXqqA-cLDC0hfQPIrS5APYNsg04zkl-socWCkqkI3UIOaEe6_Qnokg0GcWpLnMNQP", "secret": false, "signature": "The official account for TikTok Creators who inspire creativity and bring joy ✨\n\n⬇️ Creator Programs 💰⬇️", "total_favorited": 33349205, "uid": "6551237489917432832", "unique_id": "tiktokcreators", "verified": true, "avatar_larger": { "height": null, "uri": "https://p19-common-sign.tiktokcdn.com/tos-maliva-avt-0068/7310199914919673862~tplv-tiktokx-cropcenter-q:300:300:q70.webp", "url_prefix": null, "width": null, "url_list": [ "https://p19-common-sign.tiktokcdn.com/tos-maliva-avt-0068/7310199914919673862~tplv-tiktokx-cropcenter-q:300:300:q70.webp" ] }, "avatar_medium": { "height": null, "uri": "https://p19-common-sign.tiktokcdn.com/tos-maliva-avt-0068/7310199914919673862~tplv-tiktokx-cropcenter-q:300:300:q70.webp", "url_prefix": null, "width": null, "url_list": [ "https://p19-common-sign.tiktokcdn.com/tos-maliva-avt-0068/7310199914919673862~tplv-tiktokx-cropcenter-q:300:300:q70.webp" ] }, "avatar_thumb": { "height": null, "uri": "https://p19-common-sign.tiktokcdn.com/tos-maliva-avt-0068/7310199914919673862~tplv-tiktokx-cropcenter-q:300:300:q70.webp", "url_prefix": null, "width": null, "url_list": [ "https://p19-common-sign.tiktokcdn.com/tos-maliva-avt-0068/7310199914919673862~tplv-tiktokx-cropcenter-q:300:300:q70.webp" ] } } ] } ``` ### `POST /api/v1/scrape/tiktok/sound` One sound's metadata — title, artist, artwork, duration, usage count. | Field | Type | Required | Default | Description | | ----------------------- | ---- | -------- | ------- | ------------------------------------------- | | `clipId` *(or `music`)* | str | **yes** | `—` | Sound id, or a full tiktok.com/music/… URL. | ```bash theme={"system"} curl -X POST https://app.sideshift.app/api/v1/scrape/tiktok/sound \ -H 'x-api-key: $SIDESHIFT_SCRAPER_KEY' -H 'Content-Type: application/json' \ -d '{"clipId": "7002634556977908485"}' ``` **Response** — the `data` object: | Key | Type | | | ------------------- | ------ | ------------------------------------- | | `music_info` | object | | | `rec_list` | array | | | `similar_music` | array | | | `similar_music_ids` | array | | | `status_code` | number | Platform status code. `0` is success. | | `status_msg` | string | Platform status message. | ```json theme={"system"} { "status_code": 0, "status_msg": "", "music_info": { "album": null, "author": "🇺🇸", "duration": 6, "id": "7002634556977908485", "id_str": "7002634556977908485", "is_original": true, "is_original_sound": true, "mid": "7002634556977908485", "owner_nickname": "🇺🇸", "title": "original sound - duyoungin", "user_count": 982, "cover_large": { "height": null, "uri": "https://p19-common-sign.tiktokcdn.com/tos-maliva-avt-0068/7350346788798218286~tplv-tiktokx-cropcenter:720:720.webp", "url_prefix": null, "width": null, "url_list": [ "https://p19-common-sign.tiktokcdn.com/tos-maliva-avt-0068/7350346788798218286~tplv-tiktokx-cropcenter:720:720.webp" ] }, "cover_medium": { "height": null, "uri": "https://p19-common-sign.tiktokcdn.com/tos-maliva-avt-0068/7350346788798218286~tplv-tiktokx-cropcenter:720:720.webp", "url_prefix": null, "width": null, "url_list": [ "https://p19-common-sign.tiktokcdn.com/tos-maliva-avt-0068/7350346788798218286~tplv-tiktokx-cropcenter:720:720.webp" ] }, "cover_thumb": { "height": null, "uri": "https://p19-common-sign.tiktokcdn.com/tos-maliva-avt-0068/7350346788798218286~tplv-tiktokx-cropcenter:720:720.webp", "url_prefix": null, "width": null, "url_list": [ "https://p19-common-sign.tiktokcdn.com/tos-maliva-avt-0068/7350346788798218286~tplv-tiktokx-cropcenter:720:720.webp" ] }, "play_url": { "height": null, "uri": "https://sf16-ies-music-va.tiktokcdn.com/obj/musically-maliva-obj/7002634676770999045.mp3", "url_prefix": null, "width": null, "url_list": [ "https://sf16-ies-music-va.tiktokcdn.com/obj/musically-maliva-obj/7002634676770999045.mp3" ] } }, "rec_list": [], "similar_music": [], "similar_music_ids": [] } ``` `music_info` fields: | Field | Type | Example | | ------------------- | ------- | -------------------------------------------- | | `id` | string | `"7002634556977908485"` | | `id_str` | string | `"7002634556977908485"` | | `mid` | string | `"7002634556977908485"` | | `title` | string | `"original sound - duyoungin"` | | `author` | string | `"🇺🇸"` | | `owner_nickname` | string | `"🇺🇸"` | | `album` | null | | | `duration` | number | `6` | | `is_original` | boolean | `true` | | `is_original_sound` | boolean | `true` | | `play_url` | object | nested: `uri`, `url_list`, `width`, `height` | | `cover_thumb` | object | nested: `uri`, `url_list`, `width`, `height` | | `cover_medium` | object | nested: `uri`, `url_list`, `width`, `height` | | `cover_large` | object | nested: `uri`, `url_list`, `width`, `height` | | `user_count` | number | `982` | ### `POST /api/v1/scrape/tiktok/sound-posts` The videos using a sound. | Field | Type | Required | Default | Description | | ----------------------- | ---- | -------- | ------- | -------------------------------------------------------------------------------------------------- | | `clipId` *(or `music`)* | str | **yes** | `—` | Sound id, or a full tiktok.com/music/… URL. | | `cursor` | str | no | `'0'` | Pagination cursor — echo back the `cursor` from the previous response. Omit it for the first page. | ```bash theme={"system"} curl -X POST https://app.sideshift.app/api/v1/scrape/tiktok/sound-posts \ -H 'x-api-key: $SIDESHIFT_SCRAPER_KEY' -H 'Content-Type: application/json' \ -d '{"clipId": "7002634556977908485", "cursor": "0"}' ``` **Response** — the `data` object: | Key | Type | | | ------------------- | --------------- | -------------------------------------------------------------- | | `aweme_list` | array of `post` | | | `cursor` | string | Pass back on the next call. `null` once the list is exhausted. | | `has_more` | boolean | Whether another page exists. | | `status_code` | number | Platform status code. `0` is success. | | `status_msg` | string | Platform status message. | | `extra` | null | Platform tracing block. Always `null` here. | | `log_pb` | null | Platform tracing block. Always `null` here. | | `can_pin_video` | boolean | | | `need_lazy_loading` | boolean | | | `music_id` | string | Echo of what you queried. | ```json theme={"system"} { "can_pin_video": false, "cursor": "12", "extra": null, "has_more": true, "log_pb": null, "music_id": "7002634556977908485", "need_lazy_loading": false, "status_code": 0, "status_msg": "", "aweme_list": [ { "anchors": null, "author_user_id": "6764339504008446982", "aweme_id": "7014949174089125125", "aweme_type": 0, "create_time": 1633295132, "create_time_utc": "2021-10-03T21:05:32.000Z", "desc": "Tu 4@ se quiere quedar encerrado en una habitación contigo 🙊 #yarelyly", "desc_language": null, "image_post_info": null, "is_ad": false, "is_eligible_for_commission": null, "is_nff_or_nr": false, "is_paid_partnership": null, "is_top": 0, "item_comment_settings": 0, "media_id": "v09044g40000c5d1kirc77uf6a6olms0", "music": null, "region": "VE", "shop_product_url": null, "url": "https://www.tiktok.com/@yarelyly/video/7014949174089125125", "author": { "events": null, "language": null, "nickname": "Yarelyly", "region": "VE", "sec_uid": null, "short_id": null, "signature": null, "social_info": null, "uid": "6764339504008446982", "unique_id": "yarelyly", "avatar_larger": { "height": null, "uri": "https://p16-common-sign.tiktokcdn.com/tos-alisg-avt-0068/ff9e02109b824cb6757b43279e970164~tplv-tiktokx-cropcenter-q:300:300:q70.jpeg", "url_prefix": null, "width": null, "url_list": [ "https://p16-common-sign.tiktokcdn.com/tos-alisg-avt-0068/ff9e02109b824cb6757b43279e970164~tplv-tiktokx-cropcenter-q:300:300:q70.jpeg" ] }, "avatar_medium": { "height": null, "uri": "https://p16-common-sign.tiktokcdn.com/tos-alisg-avt-0068/ff9e02109b824cb6757b43279e970164~tplv-tiktokx-cropcenter-q:300:300:q70.jpeg", "url_prefix": null, "width": null, "url_list": [ "https://p16-common-sign.tiktokcdn.com/tos-alisg-avt-0068/ff9e02109b824cb6757b43279e970164~tplv-tiktokx-cropcenter-q:300:300:q70.jpeg" ] }, "avatar_thumb": { "height": null, "uri": "https://p16-common-sign.tiktokcdn.com/tos-alisg-avt-0068/ff9e02109b824cb6757b43279e970164~tplv-tiktokx-cropcenter-q:300:300:q70.jpeg", "url_prefix": null, "width": null, "url_list": [ "https://p16-common-sign.tiktokcdn.com/tos-alisg-avt-0068/ff9e02109b824cb6757b43279e970164~tplv-tiktokx-cropcenter-q:300:300:q70.jpeg" ] } }, "commerce_info": { "adv_promotable": false, "auction_ad_invited": false, "branded_content_type": 0, "is_diversion_ad": 0, "organic_log_extra": "{\"req_id\":\"2026080807114668B24AB0C15BCF9A1887\"}", "with_comment_filter_words": false }, "statistics": { "aweme_id": "7014949174089125125", "collect_count": 11940, "comment_count": 1384, "digg_count": 327240, "download_count": 11948, "forward_count": null, "lose_comment_count": null, "lose_count": null, "play_count": 2584168, "repost_count": null, "share_count": 4125, "whatsapp_share_count": null }, "video": { "data_size": 1122002, "duration": 7, "height": null, "watermark_data_size": 1141387, "width": null, "cover": { "height": null, "uri": "https://p16-common-sign.tiktokcdn.com/tos-maliva-p-0068/a68fea2b2cf04086992a8a3e2a296a61~tplv-tiktokx-cropcenter-q:300:400:q70.webp", "url_prefix": null, "width": null, "url_list": [ "https://p16-common-sign.tiktokcdn.com/tos-maliva-p-0068/a68fea2b2cf04086992a8a3e2a296a61~tplv-tiktokx-cropcenter-q:300:400:q70.webp" ] }, "download_addr": { "height": null, "uri": "https://v19.tiktokcdn.com/bfdf31e5053f1a1bfffc65a62b7e1419/6a77b7ba/video/tos/maliva/tos-maliva-ve-0068c801-us/70b68cae2d2d460ea7c00aee935d7b1a/", "url_prefix": null, "width": null, "url_list": [ "https://v19.tiktokcdn.com/bfdf31e5053f1a1bfffc65a62b7e1419/6a77b7ba/video/tos/maliva/tos-maliva-ve-0068c801-us/70b68cae2d2d460ea7c00aee935d7b1a/" ] }, "dynamic_cover": { "height": null, "uri": "https://p16-common-sign.tiktokcdn.com/tos-maliva-p-0068/114fa5c90e98427d8dccc28b06719d0a_1633295133~tplv-tiktokx-origin.image", "url_prefix": null, "width": null, "url_list": [ "https://p16-common-sign.tiktokcdn.com/tos-maliva-p-0068/114fa5c90e98427d8dccc28b06719d0a_1633295133~tplv-tiktokx-origin.image" ] }, "origin_cover": { "height": null, "uri": "https://p16-common-sign.tiktokcdn.com/tos-maliva-p-0068/8014300fd390454ea573c5bd26303448_1633295135~tplv-tiktokx-shrink-aq:360:360:q75.webp", "url_prefix": null, "width": null, "url_list": [ "https://p16-common-sign.tiktokcdn.com/tos-maliva-p-0068/8014300fd390454ea573c5bd26303448_1633295135~tplv-tiktokx-shrink-aq:360:360:q75.webp" ] }, "play_addr": { "height": null, "uri": "https://v19.tiktokcdn.com/99dba5044126bca95dbd47e28e547b57/6a77b7ba/video/tos/useast2a/tos-useast2a-ve-0068c001/02c44b704bbc47a89973defae608799f/", "url_prefix": null, "width": null, "url_list": [ "https://v19.tiktokcdn.com/99dba5044126bca95dbd47e28e547b57/6a77b7ba/video/tos/useast2a/tos-useast2a-ve-0068c001/02c44b704bbc47a89973defae608799f/" ] } } } ] } ``` ## TikTok · Hashtag ### `POST /api/v1/scrape/tiktok/hashtag` Hashtag header — description, post count and lifetime views. | Field | Type | Required | Default | Description | | --------------------------------- | ---- | -------- | ------- | ----------------------------------------------------------------------------------- | | `challenge_id` | str | no | `null` | Numeric hashtag (challenge) id | | `hashtag` *(or `challenge_name`)* | str | no | `null` | Hashtag name, also accepted as `hashtag`, with or without '#', or a /tag/{name} URL | ```bash theme={"system"} curl -X POST https://app.sideshift.app/api/v1/scrape/tiktok/hashtag \ -H 'x-api-key: $SIDESHIFT_SCRAPER_KEY' -H 'Content-Type: application/json' \ -d '{"hashtag": "fyp"}' ``` > Accepts `hashtag` (the name) or `challenge_id` (e.g. "229207"). **Response** — the `data` object: | Key | Type | | | --------- | ------ | - | | `hashtag` | object | | ```json theme={"system"} { "hashtag": { "cover_url": null, "description": null, "hashtag_id": "229207", "hashtag_link": "https://www.tiktok.com/tag/fyp", "is_challenge": false, "is_commerce": false, "is_pgc_show": false, "is_strong_music": false, "name": "fyp", "post_count": 535099733, "type": 2, "view_count": 125420751500603 } } ``` `hashtag` fields: | Field | Type | Example | | ----------------- | ------- | ---------------------------------- | | `hashtag_id` | string | `"229207"` | | `name` | string | `"fyp"` | | `description` | null | | | `post_count` | number | `534395710` | | `view_count` | number | `125407420251356` | | `cover_url` | null | | | `is_commerce` | boolean | `false` | | `is_pgc_show` | boolean | `false` | | `is_challenge` | boolean | `false` | | `is_strong_music` | boolean | `false` | | `type` | number | `2` | | `hashtag_link` | string | `"https://www.tiktok.com/tag/fyp"` | ### `POST /api/v1/scrape/tiktok/hashtag-posts` Posts carrying a hashtag. | Field | Type | Required | Default | Description | | --------------------------------- | ---- | -------- | ------- | ------------------------------------------------------------------------------------------------------- | | `challenge_id` | str | no | `null` | Numeric hashtag (challenge) id | | `hashtag` *(or `challenge_name`)* | str | no | `null` | Hashtag name, with or without '#', or a /tag/{name} URL | | `cursor` | str | no | `'0'` | Pagination cursor — echo back the `cursor` from the previous response. Omit it for the first page. | | `region` | str | no | `null` | ISO-2 region code to bias the feed (e.g. 'US'); see /api/v1/scrape/tiktok/regions for the accepted list | | `trim` | bool | no | `False` | Accepted and ignored — the full object is always returned. | ```bash theme={"system"} curl -X POST https://app.sideshift.app/api/v1/scrape/tiktok/hashtag-posts \ -H 'x-api-key: $SIDESHIFT_SCRAPER_KEY' -H 'Content-Type: application/json' \ -d '{"hashtag": "fyp", "cursor": "0"}' ``` > Passing `challenge_id` instead of the name is slightly faster; the name form returns the hashtag object alongside the posts for free. **Response** — the `data` object: | Key | Type | | | ------------ | --------------- | -------------------------------------------------------------- | | `aweme_list` | array of `post` | | | `cursor` | string | Pass back on the next call. `null` once the list is exhausted. | | `has_more` | boolean | Whether another page exists. | | `hashtag_id` | string | Echo of what you queried. | | `hashtag` | object | | ```json theme={"system"} { "cursor": "20", "has_more": true, "hashtag_id": "229207", "aweme_list": [ { "anchors": null, "author_user_id": "6756762015030641669", "aweme_id": "6915545410635435270", "aweme_type": 0, "create_time": 1610150903, "create_time_utc": "2021-01-09T00:08:23.000Z", "desc": "this sound has manifested permanently in my brain #fyp #snowman #whichvoicefitsmebest #singing", "desc_language": null, "image_post_info": null, "is_ad": false, "is_eligible_for_commission": null, "is_nff_or_nr": false, "is_paid_partnership": null, "is_top": 0, "item_comment_settings": 0, "media_id": "v09044a20000bvsf7qoqtk9j4i7e5j80", "region": "US", "shop_product_url": null, "url": "https://www.tiktok.com/@evanjmusic/video/6915545410635435270", "author": { "events": null, "language": null, "nickname": "Evan", "region": "US", "sec_uid": null, "short_id": null, "signature": null, "social_info": null, "uid": "6756762015030641669", "unique_id": "evanjmusic", "avatar_larger": { "height": null, "uri": "https://p19-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/9a2430248c74d67edc63d4ed46977566~tplv-tiktokx-cropcenter:300:300.jpeg", "url_prefix": null, "width": null, "url_list": [ "https://p19-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/9a2430248c74d67edc63d4ed46977566~tplv-tiktokx-cropcenter:300:300.jpeg" ] }, "avatar_medium": { "height": null, "uri": "https://p19-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/9a2430248c74d67edc63d4ed46977566~tplv-tiktokx-cropcenter:300:300.jpeg", "url_prefix": null, "width": null, "url_list": [ "https://p19-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/9a2430248c74d67edc63d4ed46977566~tplv-tiktokx-cropcenter:300:300.jpeg" ] }, "avatar_thumb": { "height": null, "uri": "https://p19-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/9a2430248c74d67edc63d4ed46977566~tplv-tiktokx-cropcenter:300:300.jpeg", "url_prefix": null, "width": null, "url_list": [ "https://p19-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/9a2430248c74d67edc63d4ed46977566~tplv-tiktokx-cropcenter:300:300.jpeg" ] } }, "commerce_info": { "adv_promotable": false, "auction_ad_invited": false, "branded_content_type": 0, "is_diversion_ad": 0, "organic_log_extra": "{\"req_id\":\"20260807231148B7791FF6305A7036BDF5\"}", "with_comment_filter_words": false }, "music": { "album": null, "author": "Evan", "duration": 24, "id": "6915545405321169669", "id_str": "6915545405321169669", "is_original": true, "is_original_sound": true, "mid": "6915545405321169669", "owner_nickname": "Evan", "title": "original sound - evanjmusic", "user_count": null, "cover_large": { "height": null, "uri": "https://p19-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/9a2430248c74d67edc63d4ed46977566~tplv-tiktokx-cropcenter:1080:1080.jpeg", "url_prefix": null, "width": null, "url_list": [ "https://p19-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/9a2430248c74d67edc63d4ed46977566~tplv-tiktokx-cropcenter:1080:1080.jpeg" ] }, "cover_medium": { "height": null, "uri": "https://p19-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/9a2430248c74d67edc63d4ed46977566~tplv-tiktokx-cropcenter:1080:1080.jpeg", "url_prefix": null, "width": null, "url_list": [ "https://p19-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/9a2430248c74d67edc63d4ed46977566~tplv-tiktokx-cropcenter:1080:1080.jpeg" ] }, "cover_thumb": { "height": null, "uri": "https://p19-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/9a2430248c74d67edc63d4ed46977566~tplv-tiktokx-cropcenter:1080:1080.jpeg", "url_prefix": null, "width": null, "url_list": [ "https://p19-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/9a2430248c74d67edc63d4ed46977566~tplv-tiktokx-cropcenter:1080:1080.jpeg" ] } }, "statistics": { "aweme_id": "6915545410635435270", "collect_count": 124345, "comment_count": 18910, "digg_count": 2141274, "download_count": 21110, "forward_count": null, "lose_comment_count": null, "lose_count": null, "play_count": 8109603, "repost_count": null, "share_count": 23712, "whatsapp_share_count": null }, "video": { "data_size": 2646202, "duration": 24, "height": null, "watermark_data_size": 2620840, "width": null, "cover": { "height": null, "uri": "https://p16-common-sign.tiktokcdn-us.com/tos-maliva-p-0068/d021a4d25c87437a8f4f89f81eecb90b~tplv-tiktokx-origin.image", "url_prefix": null, "width": null, "url_list": [ "https://p16-common-sign.tiktokcdn-us.com/tos-maliva-p-0068/d021a4d25c87437a8f4f89f81eecb90b~tplv-tiktokx-origin.image" ] }, "download_addr": { "height": null, "uri": "https://v16m.tiktokcdn-us.com/3e769dab22236480a211dfbd96051f15/6a76baac/video/tos/useast5/tos-useast5-ve-0068c003-tx/749d4856c16140a5938bec394b84a374/", "url_prefix": null, "width": null, "url_list": [ "https://v16m.tiktokcdn-us.com/3e769dab22236480a211dfbd96051f15/6a76baac/video/tos/useast5/tos-useast5-ve-0068c003-tx/749d4856c16140a5938bec394b84a374/" ] }, "dynamic_cover": { "height": null, "uri": "https://p19-common-sign.tiktokcdn-us.com/tos-maliva-p-0068/6cbc0da145034af69041666374b7a76f_1610150905~tplv-tiktokx-origin.image", "url_prefix": null, "width": null, "url_list": [ "https://p19-common-sign.tiktokcdn-us.com/tos-maliva-p-0068/6cbc0da145034af69041666374b7a76f_1610150905~tplv-tiktokx-origin.image" ] }, "origin_cover": { "height": null, "uri": "https://p16-common-sign.tiktokcdn-us.com/tos-maliva-p-0068/d772f60ab8a042d8a8824e365fbff7b6_1610150905~tplv-tiktokx-shrink-aq:360:360:q75.webp", "url_prefix": null, "width": null, "url_list": [ "https://p16-common-sign.tiktokcdn-us.com/tos-maliva-p-0068/d772f60ab8a042d8a8824e365fbff7b6_1610150905~tplv-tiktokx-shrink-aq:360:360:q75.webp" ] }, "play_addr": { "height": null, "uri": "https://v16m.tiktokcdn-us.com/8cd7f91799137e9ed5a6d2bc86ad7164/6a76baac/video/tos/useast5/tos-useast5-ve-0068c004-tx/e62ab361dbb24c62be3edec78d517ab9/", "url_prefix": null, "width": null, "url_list": [ "https://v16m.tiktokcdn-us.com/8cd7f91799137e9ed5a6d2bc86ad7164/6a76baac/video/tos/useast5/tos-useast5-ve-0068c004-tx/e62ab361dbb24c62be3edec78d517ab9/" ] } } } ], "hashtag": { "cover_url": null, "description": null, "hashtag_id": "229207", "hashtag_link": "https://www.tiktok.com/tag/fyp", "is_challenge": false, "is_commerce": false, "is_pgc_show": false, "is_strong_music": false, "name": "fyp", "post_count": 535099404, "type": 2, "view_count": 125420752117864 } } ``` `hashtag` fields: | Field | Type | Example | | ----------------- | ------- | ---------------------------------- | | `hashtag_id` | string | `"229207"` | | `name` | string | `"fyp"` | | `description` | null | | | `post_count` | number | `534395718` | | `view_count` | number | `125407420827330` | | `cover_url` | null | | | `is_commerce` | boolean | `false` | | `is_pgc_show` | boolean | `false` | | `is_challenge` | boolean | `false` | | `is_strong_music` | boolean | `false` | | `type` | number | `2` | | `hashtag_link` | string | `"https://www.tiktok.com/tag/fyp"` | ### `POST /api/v1/scrape/tiktok/hashtag-search` Keyword search over hashtags, with each one's post and view totals. | Field | Type | Required | Default | Description | | ------------------------- | ---- | -------- | ------- | -------------------------------------------------------------------------------------------------- | | `query` *(or `keywords`)* | str | **yes** | `—` | Search keyword / phrase. | | `cursor` | str | no | `'0'` | Pagination cursor — echo back the `cursor` from the previous response. Omit it for the first page. | ```bash theme={"system"} curl -X POST https://app.sideshift.app/api/v1/scrape/tiktok/hashtag-search \ -H 'x-api-key: $SIDESHIFT_SCRAPER_KEY' -H 'Content-Type: application/json' \ -d '{"query": "travel", "cursor": "0"}' ``` **Response** — the `data` object: | Key | Type | | | ---------- | ------- | -------------------------------------------------------------- | | `hashtags` | array | | | `cursor` | string | Pass back on the next call. `null` once the list is exhausted. | | `has_more` | boolean | Whether another page exists. | | `keywords` | string | Echo of what you queried. | ```json theme={"system"} { "cursor": "30", "has_more": true, "keywords": "travel", "hashtags": [ { "cover_url": "https://p16-amd-va.tiktokcdn.com/obj/musically-maliva-obj/6cd3395377af1ebf701faaf40d449c8c", "description": "🌟The world is a book and those who don't travel read only one page 🏄🌴Now recollect your best travel memories from your camera roll, 📷and share the stories behind!", "hashtag_id": "7884", "hashtag_link": "https://www.tiktok.com/tag/Travel", "is_challenge": false, "is_commerce": false, "is_pgc_show": false, "is_strong_music": false, "name": "Travel", "post_count": 91207723, "type": 2, "view_count": 747480036256 } ] } ``` ## TikTok · Playlist ### `POST /api/v1/scrape/tiktok/playlist` Playlist header — name, owner and video count. | Field | Type | Required | Default | Description | | ---------- | ---- | -------- | ------- | ---------------------------------------------------- | | `playlist` | str | **yes** | `—` | Playlist (mix) id, or a full /@user/playlist/... URL | ```bash theme={"system"} curl -X POST https://app.sideshift.app/api/v1/scrape/tiktok/playlist \ -H 'x-api-key: $SIDESHIFT_SCRAPER_KEY' -H 'Content-Type: application/json' \ -d '{"playlist": "7659874208872221471"}' ``` **Response** — the `data` object: | Key | Type | | | ---------- | ------ | - | | `playlist` | object | | ```json theme={"system"} { "playlist": { "creator_id": null, "creator_name": null, "creator_username": "tiktok", "name": "Behind The Breakthrough", "playlist_id": "7659874208872221471", "playlist_link": "https://www.tiktok.com/@tiktok/playlist/behind-the-breakthrough-7659874208872221471", "type": 1, "video_count": 3 } } ``` `playlist` fields: | Field | Type | Example | | ------------------ | ------ | ----------------------------------------- | | `playlist_id` | string | `"7659874208872221471"` | | `name` | string | `"Behind The Breakthrough"` | | `type` | number | `1` | | `video_count` | number | `3` | | `creator_id` | null | | | `creator_username` | string | `"tiktok"` | | `creator_name` | null | | | `playlist_link` | string | `"https://www.tiktok.com/@tiktok/playli…` | ## TikTok · Collection ### `POST /api/v1/scrape/tiktok/collection` Collection header — name, owner and video count. | Field | Type | Required | Default | Description | | ------------------------- | ---- | -------- | ------- | ------------------------------------------------------- | | `url` *(or `collection`)* | str | **yes** | `—` | Collection id, or a full tiktok.com/collection/... URL. | ```bash theme={"system"} curl -X POST https://app.sideshift.app/api/v1/scrape/tiktok/collection \ -H 'x-api-key: $SIDESHIFT_SCRAPER_KEY' -H 'Content-Type: application/json' \ -d '{"url": "7394627756635573022"}' ``` **Response** — the `data` object: | Key | Type | | | ------------ | ------ | - | | `collection` | object | | ```json theme={"system"} { "collection": { "collection_id": "7394627756635573022", "creator_id": "107955", "creator_name": "TikTok", "creator_username": null, "name": "Summer of Sports", "state": 3, "video_count": 139 } } ``` `collection` fields: | Field | Type | Example | | ------------------ | ------ | ----------------------- | | `collection_id` | string | `"7394627756635573022"` | | `name` | string | `"Summer of Sports"` | | `video_count` | number | `139` | | `state` | number | `3` | | `creator_id` | string | `"107955"` | | `creator_username` | null | | | `creator_name` | string | `"TikTok"` | ### `POST /api/v1/scrape/tiktok/collection-posts` Videos saved inside a public collection. | Field | Type | Required | Default | Description | | ------------------------- | ---- | -------- | ------- | -------------------------------------------------------------------------------------------------- | | `url` *(or `collection`)* | str | **yes** | `—` | Collection id, or a full tiktok.com/collection/... URL. | | `cursor` | str | no | `'0'` | Pagination cursor — echo back the `cursor` from the previous response. Omit it for the first page. | ```bash theme={"system"} curl -X POST https://app.sideshift.app/api/v1/scrape/tiktok/collection-posts \ -H 'x-api-key: $SIDESHIFT_SCRAPER_KEY' -H 'Content-Type: application/json' \ -d '{"url": "7394627756635573022", "cursor": "0"}' ``` > This surface answers in TikTok's WEB shape (`id`/`desc`/`stats`/`createTime`) and pages on `max_cursor`. **Response** — the `data` object: | Key | Type | | | --------------- | -------------------------- | ---------------------------------------------------------- | | `collection_id` | string | Echo of what you queried. | | `videos` | array of `collection post` | | | `has_more` | boolean | Whether another page exists. | | `max_cursor` | string | Pagination cursor for this surface. `null` once exhausted. | | `status_code` | number | Platform status code. `0` is success. | | `status_msg` | string | Platform status message. | ```json theme={"system"} { "collection_id": "7394627756635573022", "has_more": true, "max_cursor": "30", "status_code": 0, "status_msg": "", "videos": [ { "AIGCDescription": null, "CategoryType": null, "IsHDBitrate": null, "ShowAIGC": null, "anchors": null, "createTime": 1722860874, "desc": null, "id": "7399631056783035690", "author": { "id": "6791598551904076805", "nickname": "Noah Lyles", "uniqueId": "nojo18" }, "stats": { "collectCount": 38999, "commentCount": 3102, "diggCount": 500605, "playCount": 3341459, "shareCount": 22575 }, "video": { "cover": "https://p16-common-sign.tiktokcdn.com/tos-useast5-p-0068-tx/oYQIDWNuYCYeHwMTg8ffGkBAQLFT0YdJD7qAjS~tplv-tiktokx-cropcenter-q:300:400:q70.webp", "duration": 48, "height": null, "width": null } } ] } ``` ### `POST /api/v1/scrape/tiktok/collections` Every public collection a creator has published. | Field | Type | Required | Default | Description | | --------------------------- | ---- | -------- | ------- | -------------------------------------------------------------------------------------------------- | | `handle` *(or `unique_id`)* | str | no | `null` | Creator's username/handle (with or without @). | | `user_id` | str | no | `null` | Numeric TikTok user id — an alternative to unique\_id | | `cursor` | str | no | `'0'` | Pagination cursor — echo back the `cursor` from the previous response. Omit it for the first page. | ```bash theme={"system"} curl -X POST https://app.sideshift.app/api/v1/scrape/tiktok/collections \ -H 'x-api-key: $SIDESHIFT_SCRAPER_KEY' -H 'Content-Type: application/json' \ -d '{"handle": "tiktok", "cursor": "0"}' ``` **Response** — the `data` object: | Key | Type | | | ------------- | ------- | -------------------------------------------------------------- | | `collections` | array | | | `cursor` | null | Pass back on the next call. `null` once the list is exhausted. | | `has_more` | boolean | Whether another page exists. | | `unique_id` | string | Echo of what you queried. | | `user_id` | null | Echo of what you queried. | ```json theme={"system"} { "cursor": null, "has_more": false, "unique_id": "tiktok", "user_id": null, "collections": [ { "collection_id": "7394627756635573022", "creator_id": null, "creator_name": null, "creator_username": null, "name": "Summer of Sports", "state": 3, "video_count": 139 } ] } ``` ### `POST /api/v1/scrape/tiktok/playlists` Every playlist a creator has published. | Field | Type | Required | Default | Description | | --------------------------- | ---- | -------- | ------- | -------------------------------------------------------------------------------------------------- | | `handle` *(or `unique_id`)* | str | no | `null` | Creator's username/handle (with or without @). | | `user_id` | str | no | `null` | Numeric TikTok user id — an alternative to unique\_id | | `cursor` | str | no | `'0'` | Pagination cursor — echo back the `cursor` from the previous response. Omit it for the first page. | ```bash theme={"system"} curl -X POST https://app.sideshift.app/api/v1/scrape/tiktok/playlists \ -H 'x-api-key: $SIDESHIFT_SCRAPER_KEY' -H 'Content-Type: application/json' \ -d '{"handle": "tiktok", "cursor": "0"}' ``` **Response** — the `data` object: | Key | Type | | | ----------- | ------- | -------------------------------------------------------------- | | `playlists` | array | | | `cursor` | null | Pass back on the next call. `null` once the list is exhausted. | | `has_more` | boolean | Whether another page exists. | | `unique_id` | string | Echo of what you queried. | | `user_id` | null | Echo of what you queried. | ```json theme={"system"} { "cursor": null, "has_more": false, "unique_id": "tiktok", "user_id": null, "playlists": [ { "creator_id": null, "creator_name": null, "creator_username": "tiktok", "name": "Behind The Breakthrough", "playlist_id": "7659874208872221471", "playlist_link": "https://www.tiktok.com/@tiktok/playlist/behind-the-breakthrough-7659874208872221471", "type": 1, "video_count": null } ] } ``` ## TikTok · Discovery ### `POST /api/v1/scrape/tiktok/search` Keyword search over videos, with recency and sort filters. | Field | Type | Required | Default | Description | | ------------------------- | ---- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | `query` *(or `keywords`)* | str | **yes** | `—` | Search keyword / phrase. | | `cursor` | str | no | `'0'` | Pagination cursor — echo back the `cursor` from the previous response. Omit it for the first page. | | `region` | str | no | `null` | ISO-2 region code to search from (e.g. 'US'); see /api/v1/scrape/tiktok/regions | | `publish_time` | int | no | `0` | Recency filter in days: 0 all-time (default), 1 past 24 h, 7 this week, 30 this month, 90 last 3 months, 180 last 6 months | | `sort_type` | int | no | `0` | Sort order: 0 relevance (default), 1 most-liked, 3 most recent | | `trim` | bool | no | `False` | Accepted and ignored — the full object is always returned. | | `date_posted` | str | no | `null` | Named recency window: all-time, yesterday, this-week, this-month, last-3-months, last-6-months. Supersedes publish\_time when both are sent. | | `sort_by` | str | no | `null` | Named ranking: relevance, most-liked, date-posted. Supersedes sort\_type when both are sent. | ```bash theme={"system"} curl -X POST https://app.sideshift.app/api/v1/scrape/tiktok/search \ -H 'x-api-key: $SIDESHIFT_SCRAPER_KEY' -H 'Content-Type: application/json' \ -d '{"query": "cooking", "cursor": "0"}' ``` > `date_posted`: all-time · yesterday · this-week · this-month · last-3-months · last-6-months. `sort_by`: relevance · most-liked · date-posted. **Response** — the `data` object: | Key | Type | | | ------------------ | --------------- | -------------------------------------------------------------- | | `search_item_list` | array of `post` | | | `cursor` | string | Pass back on the next call. `null` once the list is exhausted. | | `has_more` | boolean | Whether another page exists. | | `keywords` | string | Echo of what you queried. | ```json theme={"system"} { "cursor": "30", "has_more": true, "keywords": "cooking", "search_item_list": [ { "anchors": null, "author_user_id": "7595092978478515208", "aweme_id": "7641078074167102727", "aweme_type": 0, "create_time": 1779077132, "create_time_utc": "2026-05-18T04:05:32.000Z", "desc": "Cooking yummy wash fish with eggs braised recipe", "desc_language": null, "image_post_info": null, "is_ad": false, "is_eligible_for_commission": null, "is_nff_or_nr": false, "is_paid_partnership": null, "is_top": 0, "item_comment_settings": 0, "media_id": "v14025g50000d858cvvog65ksrlgv7ig", "region": "KH", "shop_product_url": null, "url": "https://www.tiktok.com/@goodcook331/video/7641078074167102727", "author": { "events": null, "language": null, "nickname": "Good Cook", "region": "KH", "sec_uid": null, "short_id": null, "signature": null, "social_info": null, "uid": "7595092978478515208", "unique_id": "goodcook331", "avatar_larger": { "height": null, "uri": "https://p16-common-sign.tiktokcdn-us.com/tos-alisg-avt-0068/3b48883939a96eb04861eb46fff5b035~tplv-tiktokx-cropcenter-q:300:300:q70.jpeg", "url_prefix": null, "width": null, "url_list": [ "https://p16-common-sign.tiktokcdn-us.com/tos-alisg-avt-0068/3b48883939a96eb04861eb46fff5b035~tplv-tiktokx-cropcenter-q:300:300:q70.jpeg" ] }, "avatar_medium": { "height": null, "uri": "https://p16-common-sign.tiktokcdn-us.com/tos-alisg-avt-0068/3b48883939a96eb04861eb46fff5b035~tplv-tiktokx-cropcenter-q:300:300:q70.jpeg", "url_prefix": null, "width": null, "url_list": [ "https://p16-common-sign.tiktokcdn-us.com/tos-alisg-avt-0068/3b48883939a96eb04861eb46fff5b035~tplv-tiktokx-cropcenter-q:300:300:q70.jpeg" ] }, "avatar_thumb": { "height": null, "uri": "https://p16-common-sign.tiktokcdn-us.com/tos-alisg-avt-0068/3b48883939a96eb04861eb46fff5b035~tplv-tiktokx-cropcenter-q:300:300:q70.jpeg", "url_prefix": null, "width": null, "url_list": [ "https://p16-common-sign.tiktokcdn-us.com/tos-alisg-avt-0068/3b48883939a96eb04861eb46fff5b035~tplv-tiktokx-cropcenter-q:300:300:q70.jpeg" ] } }, "commerce_info": { "adv_promotable": false, "auction_ad_invited": false, "branded_content_type": 0, "is_diversion_ad": 0, "organic_log_extra": "{\"req_id\":\"20260807231153BBC929802F3B76543F28\"}", "with_comment_filter_words": false }, "music": { "album": null, "author": "Good Cook", "duration": 108, "id": "7641083260675902228", "id_str": "7641083260675902228", "is_original": true, "is_original_sound": true, "mid": "7641083260675902228", "owner_nickname": "Good Cook", "title": "original sound - goodcook331", "user_count": null, "cover_large": { "height": null, "uri": "https://p16-common-sign.tiktokcdn-us.com/tos-alisg-avt-0068/3b48883939a96eb04861eb46fff5b035~tplv-tiktokx-cropcenter-q:1080:1080:q70.jpeg", "url_prefix": null, "width": null, "url_list": [ "https://p16-common-sign.tiktokcdn-us.com/tos-alisg-avt-0068/3b48883939a96eb04861eb46fff5b035~tplv-tiktokx-cropcenter-q:1080:1080:q70.jpeg" ] }, "cover_medium": { "height": null, "uri": "https://p16-common-sign.tiktokcdn-us.com/tos-alisg-avt-0068/3b48883939a96eb04861eb46fff5b035~tplv-tiktokx-cropcenter-q:1080:1080:q70.jpeg", "url_prefix": null, "width": null, "url_list": [ "https://p16-common-sign.tiktokcdn-us.com/tos-alisg-avt-0068/3b48883939a96eb04861eb46fff5b035~tplv-tiktokx-cropcenter-q:1080:1080:q70.jpeg" ] }, "cover_thumb": { "height": null, "uri": "https://p16-common-sign.tiktokcdn-us.com/tos-alisg-avt-0068/3b48883939a96eb04861eb46fff5b035~tplv-tiktokx-cropcenter-q:1080:1080:q70.jpeg", "url_prefix": null, "width": null, "url_list": [ "https://p16-common-sign.tiktokcdn-us.com/tos-alisg-avt-0068/3b48883939a96eb04861eb46fff5b035~tplv-tiktokx-cropcenter-q:1080:1080:q70.jpeg" ] } }, "statistics": { "aweme_id": "7641078074167102727", "collect_count": 17776, "comment_count": 2778, "digg_count": 306335, "download_count": 3293, "forward_count": null, "lose_comment_count": null, "lose_count": null, "play_count": 21189938, "repost_count": null, "share_count": 33622, "whatsapp_share_count": null }, "video": { "data_size": 61369314, "duration": 108, "height": null, "watermark_data_size": 40245213, "width": null, "cover": { "height": null, "uri": "https://p19-common-sign.tiktokcdn-us.com/tos-alisg-p-0037/owEKIABAVjoCAkBqZiA5fPX4te0CUiAgUroyCo~tplv-tiktokx-cropcenter:500:800.jpeg", "url_prefix": null, "width": null, "url_list": [ "https://p19-common-sign.tiktokcdn-us.com/tos-alisg-p-0037/owEKIABAVjoCAkBqZiA5fPX4te0CUiAgUroyCo~tplv-tiktokx-cropcenter:500:800.jpeg" ] }, "download_addr": { "height": null, "uri": "https://v19.tiktokcdn-us.com/720ae2e78a445b250bcd3e2febb4a02a/6a76bb06/video/tos/alisg/tos-alisg-pve-0037/o0RPIlirYuUfJnrKBQBAEZC0V5qgkBUCmoisf3/", "url_prefix": null, "width": null, "url_list": [ "https://v19.tiktokcdn-us.com/720ae2e78a445b250bcd3e2febb4a02a/6a76bb06/video/tos/alisg/tos-alisg-pve-0037/o0RPIlirYuUfJnrKBQBAEZC0V5qgkBUCmoisf3/" ] }, "dynamic_cover": { "height": null, "uri": "https://p19-common-sign.tiktokcdn-us.com/tos-alisg-p-0037/owEKIABAVjoCAkBqZiA5fPX4te0CUiAgUroyCo~tplv-tiktokx-origin.image", "url_prefix": null, "width": null, "url_list": [ "https://p19-common-sign.tiktokcdn-us.com/tos-alisg-p-0037/owEKIABAVjoCAkBqZiA5fPX4te0CUiAgUroyCo~tplv-tiktokx-origin.image" ] }, "origin_cover": { "height": null, "uri": "https://p16-common-sign.tiktokcdn-us.com/tos-alisg-p-0037/o0TIgi0CVZsIqAkfK6lCsoGxunmBCBifU5OBrP~tplv-tiktokx-shrink-aq:360:360:q75.webp", "url_prefix": null, "width": null, "url_list": [ "https://p16-common-sign.tiktokcdn-us.com/tos-alisg-p-0037/o0TIgi0CVZsIqAkfK6lCsoGxunmBCBifU5OBrP~tplv-tiktokx-shrink-aq:360:360:q75.webp" ] }, "play_addr": { "height": null, "uri": "https://v19.tiktokcdn-us.com/debbf9976b4ad7382fc8d310bf532747/6a76bb06/video/tos/alisg/tos-alisg-pve-0037/osPqWhK4oQQ1JDGTkFKLfRnIIwGhmTAffAeWK6/", "url_prefix": null, "width": null, "url_list": [ "https://v19.tiktokcdn-us.com/debbf9976b4ad7382fc8d310bf532747/6a76bb06/video/tos/alisg/tos-alisg-pve-0037/osPqWhK4oQQ1JDGTkFKLfRnIIwGhmTAffAeWK6/" ] } } } ] } ``` ### `POST /api/v1/scrape/tiktok/photo-search` Keyword search restricted to photo (slideshow) posts. | Field | Type | Required | Default | Description | | ------------------------- | ---- | -------- | ------- | -------------------------------------------------------------------------------------------------- | | `query` *(or `keywords`)* | str | **yes** | `—` | Search keyword / phrase. | | `cursor` | str | no | `'0'` | Pagination cursor — echo back the `cursor` from the previous response. Omit it for the first page. | | `region` | str | no | `null` | ISO-2 region code to search from (e.g. 'US'); see /api/v1/scrape/tiktok/regions | ```bash theme={"system"} curl -X POST https://app.sideshift.app/api/v1/scrape/tiktok/photo-search \ -H 'x-api-key: $SIDESHIFT_SCRAPER_KEY' -H 'Content-Type: application/json' \ -d '{"query": "cooking", "cursor": "0"}' ``` **Response** — the `data` object: | Key | Type | | | ------------------ | --------------- | -------------------------------------------------------------- | | `search_item_list` | array of `post` | | | `cursor` | string | Pass back on the next call. `null` once the list is exhausted. | | `has_more` | boolean | Whether another page exists. | | `keywords` | string | Echo of what you queried. | ```json theme={"system"} { "cursor": "30", "has_more": true, "keywords": "cooking", "search_item_list": [ { "anchors": null, "author_user_id": "7159357152254968875", "aweme_id": "7636153929700576543", "aweme_type": 150, "create_time": 1777930657, "create_time_utc": "2026-05-04T21:37:37.000Z", "desc": null, "desc_language": null, "is_ad": false, "is_eligible_for_commission": null, "is_nff_or_nr": false, "is_paid_partnership": null, "is_top": 0, "item_comment_settings": 0, "media_id": null, "region": "US", "shop_product_url": null, "url": "https://www.tiktok.com/@drillyty/photo/7636153929700576543", "author": { "events": null, "language": null, "nickname": "⃟", "region": "US", "sec_uid": null, "short_id": null, "signature": null, "social_info": null, "uid": "7159357152254968875", "unique_id": "drillyty", "avatar_larger": { "height": null, "uri": "https://p19-common-sign.tiktokcdn-us.com/tos-useast8-avt-0068-tx2/0dbac9b78f088919a52104016e7b36c9~tplv-tiktokx-cropcenter-q:300:300:q70.jpeg", "url_prefix": null, "width": null, "url_list": [ "https://p19-common-sign.tiktokcdn-us.com/tos-useast8-avt-0068-tx2/0dbac9b78f088919a52104016e7b36c9~tplv-tiktokx-cropcenter-q:300:300:q70.jpeg" ] }, "avatar_medium": { "height": null, "uri": "https://p19-common-sign.tiktokcdn-us.com/tos-useast8-avt-0068-tx2/0dbac9b78f088919a52104016e7b36c9~tplv-tiktokx-cropcenter-q:300:300:q70.jpeg", "url_prefix": null, "width": null, "url_list": [ "https://p19-common-sign.tiktokcdn-us.com/tos-useast8-avt-0068-tx2/0dbac9b78f088919a52104016e7b36c9~tplv-tiktokx-cropcenter-q:300:300:q70.jpeg" ] }, "avatar_thumb": { "height": null, "uri": "https://p19-common-sign.tiktokcdn-us.com/tos-useast8-avt-0068-tx2/0dbac9b78f088919a52104016e7b36c9~tplv-tiktokx-cropcenter-q:300:300:q70.jpeg", "url_prefix": null, "width": null, "url_list": [ "https://p19-common-sign.tiktokcdn-us.com/tos-useast8-avt-0068-tx2/0dbac9b78f088919a52104016e7b36c9~tplv-tiktokx-cropcenter-q:300:300:q70.jpeg" ] } }, "commerce_info": { "adv_promotable": false, "auction_ad_invited": false, "branded_content_type": 0, "is_diversion_ad": 0, "organic_log_extra": "{\"req_id\":\"2026080723115469E59B3EE11EF454C886\"}", "with_comment_filter_words": false }, "image_post_info": { "image_post_cover": { "display_image": { "height": null, "uri": "https://p16-common-sign.tiktokcdn-us.com/tos-useast8-i-photomode-tx2/49d1d723d6d14e15a891dc04fcb3bf91~tplv-photomode-image-v1:q70.jpeg", "url_prefix": null, "width": null, "url_list": [ "https://p16-common-sign.tiktokcdn-us.com/tos-useast8-i-photomode-tx2/49d1d723d6d14e15a891dc04fcb3bf91~tplv-photomode-image-v1:q70.jpeg" ] }, "owner_watermark_image": { "height": null, "uri": "https://p16-common-sign.tiktokcdn-us.com/tos-useast8-i-photomode-tx2/49d1d723d6d14e15a891dc04fcb3bf91~tplv-photomode-image-v1:q70.jpeg", "url_prefix": null, "width": null, "url_list": [ "https://p16-common-sign.tiktokcdn-us.com/tos-useast8-i-photomode-tx2/49d1d723d6d14e15a891dc04fcb3bf91~tplv-photomode-image-v1:q70.jpeg" ] } }, "images": [ { "display_image": { "height": null, "uri": "https://p16-common-sign.tiktokcdn-us.com/tos-useast8-i-photomode-tx2/49d1d723d6d14e15a891dc04fcb3bf91~tplv-photomode-image-v1:q70.jpeg", "url_prefix": null, "width": null, "url_list": [ "https://p16-common-sign.tiktokcdn-us.com/tos-useast8-i-photomode-tx2/49d1d723d6d14e15a891dc04fcb3bf91~tplv-photomode-image-v1:q70.jpeg" ] }, "owner_watermark_image": { "height": null, "uri": "https://p16-common-sign.tiktokcdn-us.com/tos-useast8-i-photomode-tx2/49d1d723d6d14e15a891dc04fcb3bf91~tplv-photomode-image-v1:q70.jpeg", "url_prefix": null, "width": null, "url_list": [ "https://p16-common-sign.tiktokcdn-us.com/tos-useast8-i-photomode-tx2/49d1d723d6d14e15a891dc04fcb3bf91~tplv-photomode-image-v1:q70.jpeg" ] } } ] }, "music": { "album": null, "author": "🪶🎱ℳ𝒜𝒦ℰ𝒩𝒵ℐℰ🎱🪶", "duration": 13, "id": "7630573548822350605", "id_str": "7630573548822350605", "is_original": true, "is_original_sound": true, "mid": "7630573548822350605", "owner_nickname": "🪶🎱ℳ𝒜𝒦ℰ𝒩𝒵ℐℰ🎱🪶", "title": "original sound - makenzie67_1", "user_count": null, "cover_large": { "height": null, "uri": "https://p19-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/1237c559c98a5620cc479d61aceaecca~tplv-tiktokx-cropcenter-q:1080:1080:q70.jpeg", "url_prefix": null, "width": null, "url_list": [ "https://p19-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/1237c559c98a5620cc479d61aceaecca~tplv-tiktokx-cropcenter-q:1080:1080:q70.jpeg" ] }, "cover_medium": { "height": null, "uri": "https://p19-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/1237c559c98a5620cc479d61aceaecca~tplv-tiktokx-cropcenter-q:1080:1080:q70.jpeg", "url_prefix": null, "width": null, "url_list": [ "https://p19-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/1237c559c98a5620cc479d61aceaecca~tplv-tiktokx-cropcenter-q:1080:1080:q70.jpeg" ] }, "cover_thumb": { "height": null, "uri": "https://p19-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/1237c559c98a5620cc479d61aceaecca~tplv-tiktokx-cropcenter-q:1080:1080:q70.jpeg", "url_prefix": null, "width": null, "url_list": [ "https://p19-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/1237c559c98a5620cc479d61aceaecca~tplv-tiktokx-cropcenter-q:1080:1080:q70.jpeg" ] } }, "statistics": { "aweme_id": "7636153929700576543", "collect_count": null, "comment_count": 1338, "digg_count": 128163, "download_count": 67, "forward_count": null, "lose_comment_count": null, "lose_count": null, "play_count": 1139909, "repost_count": null, "share_count": 2664, "whatsapp_share_count": null }, "video": { "data_size": null, "duration": 0, "height": null, "watermark_data_size": null, "width": null, "cover": { "height": null, "uri": "https://p16-common-sign.tiktokcdn-us.com/tos-useast8-i-photomode-tx2/49d1d723d6d14e15a891dc04fcb3bf91~tplv-photomode-image-cover:640:0:q70.webp", "url_prefix": null, "width": null, "url_list": [ "https://p16-common-sign.tiktokcdn-us.com/tos-useast8-i-photomode-tx2/49d1d723d6d14e15a891dc04fcb3bf91~tplv-photomode-image-cover:640:0:q70.webp" ] }, "download_addr": { "height": null, "uri": "https://v45.tiktokcdn-us.com/836445a62b2fe9d0d55625f6a58140f8/6a7fa103/video/tos/useast5/tos-useast5-v-27dcd7-tx/oYIykQdYGwfynCZaAIewEYGqMLnesTHo3ScTYg/", "url_prefix": null, "width": null, "url_list": [ "https://v45.tiktokcdn-us.com/836445a62b2fe9d0d55625f6a58140f8/6a7fa103/video/tos/useast5/tos-useast5-v-27dcd7-tx/oYIykQdYGwfynCZaAIewEYGqMLnesTHo3ScTYg/" ] }, "dynamic_cover": { "height": null, "uri": "https://p16-common-sign.tiktokcdn-us.com/tos-useast8-i-photomode-tx2/49d1d723d6d14e15a891dc04fcb3bf91~tplv-photomode-image-cover:640:0:q70.webp", "url_prefix": null, "width": null, "url_list": [ "https://p16-common-sign.tiktokcdn-us.com/tos-useast8-i-photomode-tx2/49d1d723d6d14e15a891dc04fcb3bf91~tplv-photomode-image-cover:640:0:q70.webp" ] }, "origin_cover": { "height": null, "uri": "https://p16-common-sign.tiktokcdn-us.com/tos-useast8-i-photomode-tx2/49d1d723d6d14e15a891dc04fcb3bf91~tplv-photomode-image-cover:640:0:q70.webp", "url_prefix": null, "width": null, "url_list": [ "https://p16-common-sign.tiktokcdn-us.com/tos-useast8-i-photomode-tx2/49d1d723d6d14e15a891dc04fcb3bf91~tplv-photomode-image-cover:640:0:q70.webp" ] }, "play_addr": { "height": null, "uri": "https://v45.tiktokcdn-us.com/836445a62b2fe9d0d55625f6a58140f8/6a7fa103/video/tos/useast5/tos-useast5-v-27dcd7-tx/oYIykQdYGwfynCZaAIewEYGqMLnesTHo3ScTYg/", "url_prefix": null, "width": null, "url_list": [ "https://v45.tiktokcdn-us.com/836445a62b2fe9d0d55625f6a58140f8/6a7fa103/video/tos/useast5/tos-useast5-v-27dcd7-tx/oYIykQdYGwfynCZaAIewEYGqMLnesTHo3ScTYg/" ] } } } ] } ``` ### `POST /api/v1/scrape/tiktok/profile-search` Keyword search over creators, with follower-band and verified filters. | Field | Type | Required | Default | Description | | ------------------------- | ---- | -------- | ------- | -------------------------------------------------------------------------------------------------- | | `query` *(or `keywords`)* | str | **yes** | `—` | Search keyword / phrase. | | `cursor` | str | no | `'0'` | Pagination cursor — echo back the `cursor` from the previous response. Omit it for the first page. | | `follower_count` | str | no | `null` | Follower band: '0' no limit, '1' 0–1K, '2' 1K–10K, '3' 10K–100K, '4' 100K+ | | `profile_type` | str | no | `null` | '0' all profiles (default), '1' verified only | | `other_pref` | str | no | `null` | Search emphasis: '0' all (default), '1' match on username | | `trim` | bool | no | `False` | Accepted and ignored — the full object is always returned. | ```bash theme={"system"} curl -X POST https://app.sideshift.app/api/v1/scrape/tiktok/profile-search \ -H 'x-api-key: $SIDESHIFT_SCRAPER_KEY' -H 'Content-Type: application/json' \ -d '{"query": "cooking", "cursor": "0"}' ``` **Response** — the `data` object: | Key | Type | | | ---------- | ------------------ | -------------------------------------------------------------- | | `users` | array of `creator` | | | `cursor` | string | Pass back on the next call. `null` once the list is exhausted. | | `has_more` | boolean | Whether another page exists. | | `keywords` | string | Echo of what you queried. | ```json theme={"system"} { "cursor": "30", "has_more": true, "keywords": "cooking", "users": [ { "aweme_count": 507, "favoriting_count": 2874, "follower_count": 22235194, "following_count": 61, "nickname": "Lynja", "region": "US", "sec_uid": "MS4wLjABAAAAEuh22qcjCA4J9HIIBYyqYqu2sMIs57Y-iQZhMeCAg_TWmWYAEAwTLI7zm8Q6z41d", "signature": "[email redacted]\n\n👇Lynja’s Salts & Sugar👇", "total_favorited": 361118302, "uid": "6834290048143049733", "unique_id": "cookingwithlynja", "verified": true, "avatar_larger": { "height": null, "uri": "https://p19-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/7310587793867014186~tplv-tiktokx-cropcenter-q:1080:1080:q70.webp", "url_prefix": null, "width": null, "url_list": [ "https://p19-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/7310587793867014186~tplv-tiktokx-cropcenter-q:1080:1080:q70.webp" ] }, "avatar_medium": { "height": null, "uri": "https://p19-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/7310587793867014186~tplv-tiktokx-cropcenter-q:720:720:q70.webp", "url_prefix": null, "width": null, "url_list": [ "https://p19-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/7310587793867014186~tplv-tiktokx-cropcenter-q:720:720:q70.webp" ] }, "avatar_thumb": { "height": null, "uri": "https://p19-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/7310587793867014186~tplv-tiktokx-cropcenter-q:100:100:q70.webp", "url_prefix": null, "width": null, "url_list": [ "https://p19-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/7310587793867014186~tplv-tiktokx-cropcenter-q:100:100:q70.webp" ] } } ] } ``` ### `POST /api/v1/scrape/tiktok/top-search` TikTok's Top tab — best-matching videos, plus the creators and hashtags ranked beside them. | Field | Type | Required | Default | Description | | -------------- | ---- | -------- | ------- | ---------------------------------------------------------------------------------------- | | `query` | str | **yes** | `—` | Search term | | `cursor` | str | no | `'0'` | Pagination cursor | | `region` | str | no | `null` | ISO-2 region code to search from | | `date_posted` | str | no | `null` | Recency window: all-time, yesterday, this-week, this-month, last-3-months, last-6-months | | `sort_by` | str | no | `null` | Ranking: relevance, most-liked, date-posted | | `publish_time` | int | no | `0` | Numeric recency code — superseded by date\_posted when both are sent | | `sort_type` | int | no | `0` | Numeric sort code — superseded by sort\_by when both are sent | ```bash theme={"system"} curl -X POST https://app.sideshift.app/api/v1/scrape/tiktok/top-search \ -H 'x-api-key: $SIDESHIFT_SCRAPER_KEY' -H 'Content-Type: application/json' \ -d '{"query": "cooking", "cursor": "0"}' ``` **Response** — the `data` object: | Key | Type | | | -------------- | ------------------ | -------------------------------------------------------------- | | `items` | array of `post` | | | `users` | array of `creator` | | | `hashtags` | array | | | `cursor` | string | Pass back on the next call. `null` once the list is exhausted. | | `has_more` | boolean | Whether another page exists. | | `query` | string | Echo of what you queried. | | `publish_time` | number | | | `sort_type` | number | | ```json theme={"system"} { "cursor": "20", "has_more": true, "publish_time": 0, "query": "cooking", "sort_type": 0, "hashtags": [ { "cover_url": "https://p16-amd-va.tiktokcdn.com/obj/musically-maliva-obj/bbbcb935f04337b7e6bdb05ee1b9f5e5.jpeg", "description": null, "hashtag_id": "18973", "hashtag_link": "https://www.tiktok.com/tag/cooking", "is_challenge": false, "is_commerce": false, "is_pgc_show": false, "is_strong_music": false, "name": "cooking", "post_count": 18632328, "type": 2, "view_count": 537338240790 } ], "items": [ { "content_type": "video", "create_time": "2026-08-07T17:28:52.000Z", "desc": "KITCHEN TELEPHONE EP5 - oKoNoMiYaKi… if you have been following along, then you know today is my turn to take a few ingredients from @Sarah recipe and turn it into something new! #cooking #Recipe #quickrecipes #lunchideas #EasyRecipes", "desc_language": null, "id": "7671342896217361678", "images": null, "is_ad": false, "is_eligible_for_commission": null, "is_paid_partnership": null, "is_top": 0, "region": "US", "shop_product_url": null, "url": "https://www.tiktok.com/@iankyo/video/7671342896217361678", "author": { "events": null, "language": null, "nickname": "Ian Fujimoto", "region": "US", "sec_uid": null, "short_id": null, "signature": null, "social_info": null, "uid": "6900279311132328966", "unique_id": "iankyo", "avatar_larger": { "height": null, "uri": "https://p19-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/da6c5bb9f1629b4f5c5fdd681e424544~tplv-tiktokx-cropcenter-q:300:300:q70.jpeg", "url_prefix": null, "width": null, "url_list": [ "https://p19-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/da6c5bb9f1629b4f5c5fdd681e424544~tplv-tiktokx-cropcenter-q:300:300:q70.jpeg" ] }, "avatar_medium": { "height": null, "uri": "https://p19-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/da6c5bb9f1629b4f5c5fdd681e424544~tplv-tiktokx-cropcenter-q:300:300:q70.jpeg", "url_prefix": null, "width": null, "url_list": [ "https://p19-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/da6c5bb9f1629b4f5c5fdd681e424544~tplv-tiktokx-cropcenter-q:300:300:q70.jpeg" ] }, "avatar_thumb": { "height": null, "uri": "https://p19-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/da6c5bb9f1629b4f5c5fdd681e424544~tplv-tiktokx-cropcenter-q:300:300:q70.jpeg", "url_prefix": null, "width": null, "url_list": [ "https://p19-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/da6c5bb9f1629b4f5c5fdd681e424544~tplv-tiktokx-cropcenter-q:300:300:q70.jpeg" ] } }, "music": { "album": "summer like this", "author": "ktmelodies", "duration": 60, "id": "7465426882822883344", "id_str": "7465426882822883344", "is_original": false, "is_original_sound": false, "mid": "7465426882822883344", "owner_nickname": "ktmelodies", "title": "summer like this", "user_count": null, "cover_large": { "height": null, "uri": "https://p16-common.tiktokcdn-us.com/tos-alisg-v-2774/oYwEhwYAWiZ1B5iFMzr6AECqjAKAUpPACAaR5~tplv-tiktokx-cropcenter:720:720.jpeg", "url_prefix": null, "width": null, "url_list": [ "https://p16-common.tiktokcdn-us.com/tos-alisg-v-2774/oYwEhwYAWiZ1B5iFMzr6AECqjAKAUpPACAaR5~tplv-tiktokx-cropcenter:720:720.jpeg" ] }, "cover_medium": { "height": null, "uri": "https://p16-common.tiktokcdn-us.com/tos-alisg-v-2774/oYwEhwYAWiZ1B5iFMzr6AECqjAKAUpPACAaR5~tplv-tiktokx-cropcenter:720:720.jpeg", "url_prefix": null, "width": null, "url_list": [ "https://p16-common.tiktokcdn-us.com/tos-alisg-v-2774/oYwEhwYAWiZ1B5iFMzr6AECqjAKAUpPACAaR5~tplv-tiktokx-cropcenter:720:720.jpeg" ] }, "cover_thumb": { "height": null, "uri": "https://p16-common.tiktokcdn-us.com/tos-alisg-v-2774/oYwEhwYAWiZ1B5iFMzr6AECqjAKAUpPACAaR5~tplv-tiktokx-cropcenter:720:720.jpeg", "url_prefix": null, "width": null, "url_list": [ "https://p16-common.tiktokcdn-us.com/tos-alisg-v-2774/oYwEhwYAWiZ1B5iFMzr6AECqjAKAUpPACAaR5~tplv-tiktokx-cropcenter:720:720.jpeg" ] } }, "statistics": { "aweme_id": "7671342896217361678", "collect_count": 541, "comment_count": 46, "digg_count": 13191, "download_count": 10, "forward_count": null, "lose_comment_count": null, "lose_count": null, "play_count": 53890, "repost_count": null, "share_count": 64, "whatsapp_share_count": null }, "video": { "data_size": 6317860, "duration": 45, "height": null, "watermark_data_size": 5743899, "width": null, "cover": { "height": null, "uri": "https://p19-common-sign.tiktokcdn-us.com/tos-useast5-p-0068-tx/ooNA5BfitwOd1p2JYIBrIgACATEOiBCABzBwF2~tplv-tiktokx-cropcenter:500:800.jpeg", "url_prefix": null, "width": null, "url_list": [ "https://p19-common-sign.tiktokcdn-us.com/tos-useast5-p-0068-tx/ooNA5BfitwOd1p2JYIBrIgACATEOiBCABzBwF2~tplv-tiktokx-cropcenter:500:800.jpeg" ] }, "download_addr": { "height": null, "uri": "https://v16m.tiktokcdn-us.com/f8b617a4f68f1263e5dd15aabb315ab9/6a76baca/video/tos/useast5/tos-useast5-ve-0068c001-tx/oIRBWFDjg1TflkdAhqtNA4S2yeQEIKvNDhFYEg/", "url_prefix": null, "width": null, "url_list": [ "https://v16m.tiktokcdn-us.com/f8b617a4f68f1263e5dd15aabb315ab9/6a76baca/video/tos/useast5/tos-useast5-ve-0068c001-tx/oIRBWFDjg1TflkdAhqtNA4S2yeQEIKvNDhFYEg/" ] }, "dynamic_cover": { "height": null, "uri": "https://p16-common-sign.tiktokcdn-us.com/tos-useast5-p-0068-tx/ooNA5BfitwOd1p2JYIBrIgACATEOiBCABzBwF2~tplv-tiktokx-origin.image", "url_prefix": null, "width": null, "url_list": [ "https://p16-common-sign.tiktokcdn-us.com/tos-useast5-p-0068-tx/ooNA5BfitwOd1p2JYIBrIgACATEOiBCABzBwF2~tplv-tiktokx-origin.image" ] }, "origin_cover": { "height": null, "uri": "https://p16-common-sign.tiktokcdn-us.com/tos-useast5-p-0068-tx/okMrIpcAJBAdFaxYlwiyBI1AVC3wsAuOImfF2i~tplv-tiktokx-shrink-aq:360:360:q75.webp", "url_prefix": null, "width": null, "url_list": [ "https://p16-common-sign.tiktokcdn-us.com/tos-useast5-p-0068-tx/okMrIpcAJBAdFaxYlwiyBI1AVC3wsAuOImfF2i~tplv-tiktokx-shrink-aq:360:360:q75.webp" ] }, "play_addr": { "height": null, "uri": "https://v16m.tiktokcdn-us.com/27621cdcc8c82451c225fa46d9029a8b/6a76baca/video/tos/useast5/tos-useast5-pve-0068-tx/o8w1DNfDSQkgRvqEAKq4LdYhsBeAIEWDFgMTIg/", "url_prefix": null, "width": null, "url_list": [ "https://v16m.tiktokcdn-us.com/27621cdcc8c82451c225fa46d9029a8b/6a76baca/video/tos/useast5/tos-useast5-pve-0068-tx/o8w1DNfDSQkgRvqEAKq4LdYhsBeAIEWDFgMTIg/" ] } } } ], "users": [ { "account_creation_date": null, "avatar_medium": "https://p19-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/7310587793867014186~tplv-tiktokx-cropcenter-q:720:720:q70.webp", "avatar_thumb": "https://p19-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/7310587793867014186~tplv-tiktokx-cropcenter-q:100:100:q70.webp", "biography": "[email redacted]\n\n👇Lynja’s Salts & Sugar👇", "content_count": 507, "display_name": "Lynja", "follower_count": 22235194, "following_count": 61, "instagram_id": "cookingwithlynja", "is_ad_virtual": false, "is_under_18": false, "location": null, "privacy_status": "public", "profile_id": "6834290048143049733", "profile_image": "https://p19-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/7310587793867014186~tplv-tiktokx-cropcenter-q:1080:1080:q70.webp", "profile_link": "https://www.tiktok.com/@cookingwithlynja", "sec_uid": "MS4wLjABAAAAEuh22qcjCA4J9HIIBYyqYqu2sMIs57Y-iQZhMeCAg_TWmWYAEAwTLI7zm8Q6z41d", "total_likes": 361118302, "total_reactions": 361118302, "twitter_id": null, "username": "cookingwithlynja", "verification_status": true, "youtube_channel_id": "UCjvGPQTRr2eIEhthL5y31VQ", "youtube_channel_title": "Cooking With Lynja" } ] } ``` ### `POST /api/v1/scrape/tiktok/search-suggestions` The autocomplete terms TikTok offers for a partial query. | Field | Type | Required | Default | Description | | -------- | ---- | -------- | ------- | ------------------------------------------------- | | `query` | str | **yes** | `—` | Partial or full search term | | `region` | str | no | `null` | ISO-2 region code — suggestions are region-ranked | ```bash theme={"system"} curl -X POST https://app.sideshift.app/api/v1/scrape/tiktok/search-suggestions \ -H 'x-api-key: $SIDESHIFT_SCRAPER_KEY' -H 'Content-Type: application/json' \ -d '{"query": "coff"}' ``` **Response** — the `data` object: | Key | Type | | | ------------- | ------ | ------------------------- | | `suggestions` | array | | | `query` | string | Echo of what you queried. | | `region` | null | Echo of what you queried. | ```json theme={"system"} { "query": "coff", "region": null, "suggestions": [ { "group_id": "4928213053111302118", "language": "en", "position": 0, "score": 0.02804046, "text": "coffee" } ] } ``` ### `POST /api/v1/scrape/tiktok/trending` The trending / For You feed for a region. | Field | Type | Required | Default | Description | | -------- | ---- | -------- | ------- | -------------------------------------------------------------------------------------- | | `region` | str | no | `'US'` | ISO-2 region code (e.g. 'US'); see /api/v1/scrape/tiktok/regions for the accepted list | | `trim` | bool | no | `False` | Accepted and ignored — the full object is always returned. | ```bash theme={"system"} curl -X POST https://app.sideshift.app/api/v1/scrape/tiktok/trending \ -H 'x-api-key: $SIDESHIFT_SCRAPER_KEY' -H 'Content-Type: application/json' \ -d '{"region": "US"}' ``` > Single-shot: this feed carries no cursor, so each call returns a fresh sample rather than a page in a series. **Response** — the `data` object: | Key | Type | | | ------------ | --------------- | -------------------------------------------------------------- | | `aweme_list` | array of `post` | | | `region` | string | Echo of what you queried. | | `cursor` | null | Pass back on the next call. `null` once the list is exhausted. | | `has_more` | boolean | Whether another page exists. | ```json theme={"system"} { "cursor": null, "has_more": false, "region": "US", "aweme_list": [ { "anchors": null, "author_user_id": "7627900927097488398", "aweme_id": "7669246343336037645", "aweme_type": 0, "commerce_info": null, "create_time": 1785635586, "create_time_utc": "2026-08-02T01:53:06.000Z", "desc": null, "desc_language": null, "image_post_info": null, "is_ad": false, "is_eligible_for_commission": null, "is_nff_or_nr": null, "is_paid_partnership": null, "is_top": null, "item_comment_settings": 0, "media_id": "v12044gd0000d9na5unog65ta499kkvg", "region": "PK", "shop_product_url": null, "url": "https://www.tiktok.com/@blackvideo.002/video/7669246343336037645", "author": { "events": null, "language": null, "nickname": "blackvideo.002", "region": "PK", "sec_uid": null, "short_id": null, "signature": null, "social_info": null, "uid": "7627900927097488398", "unique_id": "blackvideo.002", "avatar_larger": { "height": null, "uri": "https://p19-common-sign.tiktokcdn.com/tos-maliva-avt-0068/69db2ade59e7b043c7682c2725798907~tplv-tiktokx-cropcenter-q:300:300:q70.webp", "url_prefix": null, "width": null, "url_list": [ "https://p19-common-sign.tiktokcdn.com/tos-maliva-avt-0068/69db2ade59e7b043c7682c2725798907~tplv-tiktokx-cropcenter-q:300:300:q70.webp" ] }, "avatar_medium": { "height": null, "uri": "https://p19-common-sign.tiktokcdn.com/tos-maliva-avt-0068/69db2ade59e7b043c7682c2725798907~tplv-tiktokx-cropcenter-q:300:300:q70.webp", "url_prefix": null, "width": null, "url_list": [ "https://p19-common-sign.tiktokcdn.com/tos-maliva-avt-0068/69db2ade59e7b043c7682c2725798907~tplv-tiktokx-cropcenter-q:300:300:q70.webp" ] }, "avatar_thumb": { "height": null, "uri": "https://p19-common-sign.tiktokcdn.com/tos-maliva-avt-0068/69db2ade59e7b043c7682c2725798907~tplv-tiktokx-cropcenter-q:300:300:q70.webp", "url_prefix": null, "width": null, "url_list": [ "https://p19-common-sign.tiktokcdn.com/tos-maliva-avt-0068/69db2ade59e7b043c7682c2725798907~tplv-tiktokx-cropcenter-q:300:300:q70.webp" ] } }, "music": { "album": null, "author": "blackvideo.002", "duration": 5, "id": "7669246392967760653", "id_str": "7669246392967760653", "is_original": false, "is_original_sound": false, "mid": "7669246392967760653", "owner_nickname": "blackvideo.002", "title": "original sound - blackvideo.002", "user_count": null, "cover_large": { "height": null, "uri": "https://p19-common-sign.tiktokcdn.com/tos-maliva-avt-0068/69db2ade59e7b043c7682c2725798907~tplv-tiktokx-cropcenter-q:1080:1080:q70.webp", "url_prefix": null, "width": null, "url_list": [ "https://p19-common-sign.tiktokcdn.com/tos-maliva-avt-0068/69db2ade59e7b043c7682c2725798907~tplv-tiktokx-cropcenter-q:1080:1080:q70.webp" ] }, "cover_medium": { "height": null, "uri": "https://p19-common-sign.tiktokcdn.com/tos-maliva-avt-0068/69db2ade59e7b043c7682c2725798907~tplv-tiktokx-cropcenter-q:1080:1080:q70.webp", "url_prefix": null, "width": null, "url_list": [ "https://p19-common-sign.tiktokcdn.com/tos-maliva-avt-0068/69db2ade59e7b043c7682c2725798907~tplv-tiktokx-cropcenter-q:1080:1080:q70.webp" ] }, "cover_thumb": { "height": null, "uri": "https://p19-common-sign.tiktokcdn.com/tos-maliva-avt-0068/69db2ade59e7b043c7682c2725798907~tplv-tiktokx-cropcenter-q:1080:1080:q70.webp", "url_prefix": null, "width": null, "url_list": [ "https://p19-common-sign.tiktokcdn.com/tos-maliva-avt-0068/69db2ade59e7b043c7682c2725798907~tplv-tiktokx-cropcenter-q:1080:1080:q70.webp" ] } }, "statistics": { "aweme_id": "7669246343336037645", "collect_count": 341, "comment_count": 24, "digg_count": 6836, "download_count": 63, "forward_count": null, "lose_comment_count": null, "lose_count": null, "play_count": 292353, "repost_count": null, "share_count": 129, "whatsapp_share_count": null }, "video": { "data_size": 33161, "duration": 5, "height": null, "watermark_data_size": 54420, "width": null, "cover": { "height": null, "uri": "https://p19-common-sign.tiktokcdn.com/tos-useast5-p-0068-tx/okoLESfo6DAwoiFHjqF6DRqAVE0gpBubIUfouE~tplv-tiktokx-shrink_ep:640:640:q78.webp", "url_prefix": null, "width": null, "url_list": [ "https://p19-common-sign.tiktokcdn.com/tos-useast5-p-0068-tx/okoLESfo6DAwoiFHjqF6DRqAVE0gpBubIUfouE~tplv-tiktokx-shrink_ep:640:640:q78.webp" ] }, "download_addr": { "height": null, "uri": "https://v77.tiktokcdn.com/ef097ac5f468382222045ce2968b8987/6a77b7c6/video/tos/alisg/tos-alisg-ve-37c799-sg/oQIuEADJRoUbAiDqoFRUfpjifL6E6E1gS0qwBw/", "url_prefix": null, "width": null, "url_list": [ "https://v77.tiktokcdn.com/ef097ac5f468382222045ce2968b8987/6a77b7c6/video/tos/alisg/tos-alisg-ve-37c799-sg/oQIuEADJRoUbAiDqoFRUfpjifL6E6E1gS0qwBw/" ] }, "dynamic_cover": { "height": null, "uri": "https://p19-common-sign.tiktokcdn.com/tos-useast5-p-0068-tx/okoLESfo6DAwoiFHjqF6DRqAVE0gpBubIUfouE~tplv-tiktokx-shrink_ep:640:640:q78.webp", "url_prefix": null, "width": null, "url_list": [ "https://p19-common-sign.tiktokcdn.com/tos-useast5-p-0068-tx/okoLESfo6DAwoiFHjqF6DRqAVE0gpBubIUfouE~tplv-tiktokx-shrink_ep:640:640:q78.webp" ] }, "origin_cover": { "height": null, "uri": "https://p16-common-sign.tiktokcdn.com/tos-useast5-p-0068-tx/oIqqBu4DE6wF0NoAAgDIbfoTRLiUDDA6EfRIpS~tplv-tiktokx-shrink-aq:360:360:q75.webp", "url_prefix": null, "width": null, "url_list": [ "https://p16-common-sign.tiktokcdn.com/tos-useast5-p-0068-tx/oIqqBu4DE6wF0NoAAgDIbfoTRLiUDDA6EfRIpS~tplv-tiktokx-shrink-aq:360:360:q75.webp" ] }, "play_addr": { "height": null, "uri": "https://v77.tiktokcdn.com/c13d417ffae6cd134ee822fb913ddd6d/6a77b7c6/video/tos/alisg/tos-alisg-ve-37c799-sg/ocpFfEB0I5RSlLg6Wf6ouEqUqwYoiDZbbAEgAD/", "url_prefix": null, "width": null, "url_list": [ "https://v77.tiktokcdn.com/c13d417ffae6cd134ee822fb913ddd6d/6a77b7c6/video/tos/alisg/tos-alisg-ve-37c799-sg/ocpFfEB0I5RSlLg6Wf6ouEqUqwYoiDZbbAEgAD/" ] } } } ] } ``` ### `POST /api/v1/scrape/tiktok/regions` The region codes accepted by the region-scoped endpoints. Takes no parameters. ```bash theme={"system"} curl -X POST https://app.sideshift.app/api/v1/scrape/tiktok/regions \ -H 'x-api-key: $SIDESHIFT_SCRAPER_KEY' -H 'Content-Type: application/json' \ -d '{}' ``` > A static list — cache it rather than fetching it per request. **Response** — the `data` object: | Key | Type | | | --------- | ------ | ------------------------------------------------ | | `regions` | array | | | `total` | number | Total across the whole list, not just this page. | ```json theme={"system"} { "total": 242, "regions": [ { "code": "AD", "name": "Andorra" } ] } ``` ## TikTok · Comments ### `POST /api/v1/scrape/tiktok/comment-replies` The reply thread under one comment. | Field | Type | Required | Default | Description | | ----------------------- | ---- | -------- | ------- | -------------------------------------------------------------------------------------------------- | | `url` *(or `video_id`)* | str | **yes** | `—` | Numeric video id, or any full TikTok video/photo URL. | | `comment_id` | str | **yes** | `—` | Numeric id of the comment whose replies to fetch | | `cursor` | str | no | `'0'` | Pagination cursor — echo back the `cursor` from the previous response. Omit it for the first page. | ```bash theme={"system"} curl -X POST https://app.sideshift.app/api/v1/scrape/tiktok/comment-replies \ -H 'x-api-key: $SIDESHIFT_SCRAPER_KEY' -H 'Content-Type: application/json' \ -d '{"url": "7612965843596479751", "comment_id": "7612966844110914334"}' ``` > TikTok nests exactly one level, so replies never have replies. TikTok's own reply cursor is off by one — page 2 repeats page 1's last reply — so de-duplicate on `cid`, and use `total` for the real thread size. Requesting a thread in a single page avoids it entirely. **Response** — the `data` object: | Key | Type | | | ------------- | ------------------ | -------------------------------------------------------------- | | `comments` | array of `comment` | | | `cursor` | null | Pass back on the next call. `null` once the list is exhausted. | | `has_more` | boolean | Whether another page exists. | | `status_code` | number | Platform status code. `0` is success. | | `status_msg` | string | Platform status message. | | `extra` | null | Platform tracing block. Always `null` here. | | `log_pb` | null | Platform tracing block. Always `null` here. | | `total` | number | Total across the whole list, not just this page. | | `aweme_id` | string | Echo of what you queried. | | `comment_id` | string | Echo of what you queried. | ```json theme={"system"} { "aweme_id": "7612965843596479751", "comment_id": "7612966844110914334", "cursor": null, "extra": null, "has_more": false, "log_pb": null, "status_code": 0, "status_msg": "", "total": 4, "comments": [ { "aweme_id": "7612965843596479751", "cid": "7612967610280805138", "comment_language": null, "create_time": 1772532161, "digg_count": 38, "image_list": null, "is_author_digged": null, "reply_comment": null, "reply_comment_total": null, "reply_id": null, "reply_to_reply_id": null, "status": 1, "text": "Thx𓀠𓀠", "text_extra": null, "user_digged": null, "user": { "aweme_count": 0, "create_time": null, "favoriting_count": 0, "follower_count": 0, "following_count": 0, "language": null, "nickname": "ちい/Chii", "region": "JP", "sec_uid": "MS4wLjABAAAANiBD2T6ao7u2cE5Xj1zRRiVjShx-oKRUIDUFgHqmbyUkUOH-bk4iehKJ7eOsUkrJ", "secret": false, "signature": "⸝⋆꙳⟡.· ⋆ 𖦹ܾ 𖥧🪵🌿\n\n🗺ɪɴꜱᴛᴀɢʀᴀᴍ : @ artchiis\n\nꜱᴜʙ:@たいやきくん(ちい) 🚹: @壱", "total_favorited": 0, "uid": "7093407411964986370", "unique_id": "artchiis" } } ] } ``` ## TikTok · Media ### `POST /api/v1/scrape/tiktok/transcript` A video's caption track, as plain text and raw WEBVTT. | Field | Type | Required | Default | Description | | -------------------- | ---- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `url` | str | **yes** | `—` | TikTok video URL, or a bare numeric video id | | `language` | str | no | `null` | Pick a specific track by language code (e.g. 'en'). Omit to prefer a creator-authored track, then English. | | `use_ai_as_fallback` | bool | no | `False` | Applies only to videos with no caption track, which would require speech-to-text. Speech-to-text fallback is not enabled, so such videos report a clear 501 rather than silently returning nothing. | ```bash theme={"system"} curl -X POST https://app.sideshift.app/api/v1/scrape/tiktok/transcript \ -H 'x-api-key: $SIDESHIFT_SCRAPER_KEY' -H 'Content-Type: application/json' \ -d '{"url": "https://www.tiktok.com/@tiktok/video/7612965843596479751"}' ``` > A genuine caption track, not speech recognition. Short share links (`vm.tiktok.com`) are rejected with a 400 — expand them first, or pass the bare numeric id. **Response** — the `data` object: | Key | Type | | | ------------------- | ------ | - | | `id` | string | | | `url` | string | | | `transcript` | null | | | `transcript_vtt` | null | | | `language` | null | | | `is_auto_generated` | null | | | `available_tracks` | array | | ```json theme={"system"} { "id": "7612965843596479751", "is_auto_generated": null, "language": null, "transcript": null, "transcript_vtt": null, "url": "https://www.tiktok.com/@tiktok/video/7612965843596479751", "available_tracks": [] } ``` ## TikTok · Ads ### `POST /api/v1/scrape/tiktok/ads` TikTok's Top Ads library — the best-performing public ads. | Field | Type | Required | Default | Description | | -------------- | ---- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `page` | int | no | `1` | 1-indexed result page | | `cursor` | str | no | `null` | Pagination cursor — echo back the `cursor` from the previous response. Omit it for the first page.. Equivalent to `page` (this library pages by number); when both are sent, `cursor` wins. | | `limit` | int | no | `20` | Ads per page (max 20; higher values are silently clamped) | | `period` | int | no | `null` | Look-back window in days: 7, 30 or 180 | | `country_code` | str | no | `null` | Comma-separated ISO-2 markets (e.g. 'US,CA') | | `ad_language` | str | no | `null` | Comma-separated language codes (e.g. 'en,de') | | `order_by` | str | no | `null` | Ranking metric: 'impression' (reach), 'ctr', 'like', 'cvr', 'play\_6s\_rate', 'play\_2s\_rate' | | `industry` | str | no | `null` | Comma-separated industry codes (e.g. '28000000000,24000000000') | | `ad_format` | str | no | `null` | '1' Spark Ads, '2' non-Spark Ads | | `objective` | str | no | `null` | Comma-separated campaign objectives: 1 traffic, 2 app installs, 3 conversions, 4 video views, 5 reach, 8 lead generation, 15 product sales | | `like` | str | no | `null` | Like percentile band: '1' top 1–20%, '2' 21–40%, '3' 41–60%, '4' 61–80%, '5' 81–100% | | `keyword` | str | no | `null` | Free-text keyword to search the ads library | ```bash theme={"system"} curl -X POST https://app.sideshift.app/api/v1/scrape/tiktok/ads \ -H 'x-api-key: $SIDESHIFT_SCRAPER_KEY' -H 'Content-Type: application/json' \ -d '{"country_code": "US", "period": 7}' ``` > Spend is not published for any ad, so `cost` is a band rather than a figure. `ctr` and `like` are the library's real metrics. **Response** — the `data` object: | Key | Type | | | ----------- | ------- | -------------------------------------------------------------- | | `ads` | array | | | `cursor` | null | Pass back on the next call. `null` once the list is exhausted. | | `has_more` | boolean | Whether another page exists. | | `page` | number | | | `page_size` | number | | | `total` | number | Total across the whole list, not just this page. | ```json theme={"system"} { "cursor": null, "has_more": false, "page": 1, "page_size": 20, "total": 20, "ads": [ { "ad_id": "7668163246391033864", "brand_name": null, "comment_count": null, "cost_level": 0, "countries": null, "ctr": 0.93, "has_summary": null, "has_voice_over": null, "highlight_text": null, "industry_key": "label_23116000000", "is_search_ad": true, "keywords": null, "landing_page": null, "like_count": 978, "objective_key": "campaign_objective_reach", "objectives": null, "share_count": null, "source": null, "source_key": null, "title": "Yas Nomura | My Ultimate Live Guitar | Donner Live Asia Tour 🎸Learn more about HLX-500 Headless Guitar：https://www.donnermusic.com/en-US/buy/8669872324746 -------------------------------------- 🎸CREATE THE MOMENT #yasnomura #DonnerLive #donnerliveasiatour #donnerlivejapan…", "video": { "cover_url": "https://p16-common-sign.tiktokcdn.com/tos-alisg-p-37c799-sg/ocxiAUIW5AAUzt4gBEmulG9JPUFnqlqBEqali~tplv-noop.image", "duration_seconds": 93.376, "height": 1024, "video_id": "v12025gd0000d9lb757og65pl1ih8m20", "video_link": "https://v16m-default.tiktokcdn.com/f403a79d2c5c86547c4dc598a7ca6437/6a76baff/video/tos/alisg/tos-alisg-ve-37c799-sg/oAA4RoEiUUm5tIRCAzElaqiQBqFoGEWUilPgq/", "width": 576, "video_links_by_quality": { "720p": "https://v16m-default.tiktokcdn.com/f403a79d2c5c86547c4dc598a7ca6437/6a76baff/video/tos/alisg/tos-alisg-ve-37c799-sg/oAA4RoEiUUm5tIRCAzElaqiQBqFoGEWUilPgq/" } } } ] } ``` ### `POST /api/v1/scrape/tiktok/ad` The full record for one ad from the Top Ads library. | Field | Type | Required | Default | Description | | ---------------------------- | ---- | -------- | ------- | ----------------------------------------------------------- | | `ad_id` *(or `material_id`)* | str | **yes** | `—` | Ad (material) id, as returned by /api/v1/scrape/tiktok/ads. | ```bash theme={"system"} curl -X POST https://app.sideshift.app/api/v1/scrape/tiktok/ad \ -H 'x-api-key: $SIDESHIFT_SCRAPER_KEY' -H 'Content-Type: application/json' \ -d '{"ad_id": "7667849995747770388"}' ``` **Response** — the `data` object: | Key | Type | | | --------------------------- | ------- | - | | `ad_title` | string | | | `brand_name` | string | | | `comment` | number | | | `cost` | number | | | `country_code` | array | | | `ctr` | number | | | `favorite` | boolean | | | `has_summary` | boolean | | | `highlight_text` | string | | | `id` | string | | | `industry_key` | string | | | `is_search` | boolean | | | `keyword_list` | null | | | `landing_page` | string | | | `like` | number | | | `objective_key` | string | | | `objectives` | array | | | `pattern_label` | array | | | `share` | number | | | `source` | string | | | `source_key` | number | | | `video_info` | object | | | `voice_over` | boolean | | | `creative_center_url` | string | | | `detail_analysis` | null | | | `interactive_time_analysis` | null | | | `recommended_for_you` | null | | ```json theme={"system"} { "ad_title": "[Asia’s 50 Best Bars 2026: Another Toast to Hong Kong’s Bar Scene👏] Whether you’re discovering new openings or revisiting old favourites, Hong Kong’s bar scene never disappoints🍸. And this year, it has even more reasons to celebrate, with multiple local bars making their mar…", "brand_name": "", "comment": 58, "cost": 2, "creative_center_url": "https://ads.tiktok.com/business/creativecenter/ads/detail/7667849995747770388", "ctr": 0.42, "detail_analysis": null, "favorite": false, "has_summary": false, "highlight_text": "", "id": "7667849995747770388", "industry_key": "label_23133000000", "interactive_time_analysis": null, "is_search": false, "keyword_list": null, "landing_page": "https://www.discoverhongkong.com/eng/food-and-drink.html", "like": 18090, "objective_key": "campaign_objective_reach", "recommended_for_you": null, "share": 77, "source": "Others", "source_key": 73, "voice_over": false, "country_code": [ "PH", "SG", "TH" ], "objectives": [ { "label": "campaign_objective_reach", "value": 5 } ], "pattern_label": [], "video_info": { "cover": "https://p16-common-sign.tiktokcdn.com/tos-alisg-p-0037/o0NAvAiG4RBDI0wNW2WIi1oAf0uEB1ICyDI9hi~tplv-noop.image", "duration": 35.293, "height": 1024, "vid": "v1c044g50000d9kcmuvog65kr88cgdng", "width": 576, "video_url": { "720p": "https://v16m-default.tiktokcdn.com/1fddd33531b11fd30412ecd64006be62/6a76bac7/video/tos/alisg/tos-alisg-pve-0037c001/oEj8TLCj4GUm0MIbLALEAekgge23aoDI8fRTZA/" } } } ``` `video_info` fields: | Field | Type | Example | | ----------- | ------ | ----------------------------------------- | | `vid` | string | `"v1c044g50000d9kcmuvog65kr88cgdng"` | | `duration` | number | `35.293` | | `cover` | string | `"https://p16-common-sign.tiktokcdn.com…` | | `video_url` | object | nested: `720p` | | `width` | number | `576` | | `height` | number | `1024` | *** # Instagram — 15 platform operations Instagram's own payloads are passed through under the keys Instagram uses, so field names and nesting match what you would get from Instagram directly. ## Instagram · Profile ### `POST /api/v1/scrape/instagram/profile-details` Full public profile: identity, counts, bio links, recent posts, related accounts. | Field | Type | Required | Default | Description | | --------------- | ---- | -------- | ------- | ----------------------------------------------------- | | `cache_max_age` | str | no | `null` | Accepted and ignored — every response is a live read. | | `handle` | str | **yes** | `—` | Instagram handle (with or without @) | | `trim` | bool | no | `False` | Return only the core identity/count fields | ```bash theme={"system"} curl -X POST https://app.sideshift.app/api/v1/scrape/instagram/profile-details \ -H 'x-api-key: $SIDESHIFT_SCRAPER_KEY' -H 'Content-Type: application/json' \ -d '{"handle": "nasa"}' ``` **Response** — the `data` object: | Key | Type | | | --------- | ------- | ----------------------- | | `success` | boolean | Always `true` on a 200. | | `data` | object | | ```json theme={"system"} { "success": true, "data": { "user": { "ai_agent_owner_username": null, "ai_agent_type": null, "biography": "Making the seemingly impossible, possible. ✨", "blocked_by_viewer": false, "business_address_json": "{\"city_name\": null, \"city_id\": null, \"latitude\": null, \"longitude\": null, \"street_address\": null, \"zip_code\": null}", "business_category_name": "Government Agencies", "business_contact_method": "CALL", "business_email": null, "business_phone_number": null, "category_enum": "GOVERNMENT_ORGANIZATION", "category_name": null, "country_block": false, "eimu_id": "118750106179205", "external_url": "https://www.nasa.gov/", "external_url_linkshimmed": "https://l.instagram.com/", "fb_profile_biolink": null, "fbid": "17841401474538262", "followed_by_viewer": false, "follows_viewer": false, "full_name": "NASA", "group_metadata": null, "guardian_id": null, "has_ar_effects": false, "has_blocked_viewer": false } } } ``` `data` fields: | Field | Type | Example | | ------ | ------ | ---------------------------------------------------------------------------- | | `user` | object | nested: `ai_agent_owner_username`, `ai_agent_type`, `biography`, `bio_links` | ### `POST /api/v1/scrape/instagram/profile-summary` Profile summary keyed by numeric user id. | Field | Type | Required | Default | Description | | --------------- | ---- | -------- | ------- | ----------------------------------------------------- | | `userId` | str | **yes** | `—` | Numeric Instagram user id | | `cache_max_age` | str | no | `null` | Accepted and ignored — every response is a live read. | ```bash theme={"system"} curl -X POST https://app.sideshift.app/api/v1/scrape/instagram/profile-summary \ -H 'x-api-key: $SIDESHIFT_SCRAPER_KEY' -H 'Content-Type: application/json' \ -d '{"userId": "528817151"}' ``` **Response** — the `data` object: | Key | Type | | | ----------------------------------- | ------- | ----------------------- | | `success` | boolean | Always `true` on a 200. | | `pk` | string | | | `id` | string | | | `username` | string | | | `full_name` | string | | | `biography` | string | | | `biography_with_entities` | object | | | `profile_pic_url` | string | | | `hd_profile_pic_url_info` | object | | | `is_verified` | boolean | | | `is_private` | boolean | | | `is_business` | boolean | | | `is_professional_account` | boolean | | | `account_type` | string | | | `follower_count` | number | | | `following_count` | number | | | `media_count` | number | | | `category` | null | | | `external_url` | string | | | `bio_links` | array | | | `pronouns` | array | | | `fbid_v2` | string | | | `is_embeds_disabled` | boolean | | | `show_account_transparency_details` | boolean | | | `transparency_label` | null | | | `transparency_product` | null | | | `address_street` | string | | | `city_name` | null | | | `zip` | null | | | `is_regulated_c18` | boolean | | | `has_chaining` | boolean | | | `total_clips_count` | number | | ```json theme={"system"} { "account_type": "business", "address_street": "{\"city_name\": null, \"city_id\": null, \"latitude\": null, \"longitude\": null, \"street_address\": null, \"zip_code\": null}", "biography": "Making the seemingly impossible, possible. ✨", "category": null, "city_name": null, "external_url": "https://www.nasa.gov/", "fbid_v2": "17841401474538262", "follower_count": 104253067, "following_count": 92, "full_name": "NASA", "has_chaining": true, "id": "528817151", "is_business": true, "is_embeds_disabled": false, "is_private": false, "is_professional_account": true, "is_regulated_c18": false, "is_verified": true, "media_count": 4872, "pk": "528817151", "profile_pic_url": "https://instagram.fmem1-1.fna.fbcdn.net/v/t51.2885-19/29090066_159271188110124_1152068159029641216_n.jpg", "show_account_transparency_details": true, "success": true, "total_clips_count": 0, "transparency_label": null, "transparency_product": null, "username": "nasa", "zip": null, "bio_links": [ { "link_type": "external", "lynx_url": "https://l.instagram.com/", "title": "NASA.gov Homepage", "url": "https://www.nasa.gov/" } ], "biography_with_entities": { "raw_text": "Making the seemingly impossible, possible. ✨", "entities": [] }, "hd_profile_pic_url_info": { "url": "https://instagram.fmem1-1.fna.fbcdn.net/v/t51.2885-19/29090066_159271188110124_1152068159029641216_n.jpg" }, "pronouns": [] } ``` `biography_with_entities` fields: | Field | Type | Example | | ---------- | ------ | ----------------------------------------- | | `raw_text` | string | `"Making the seemingly impossible, poss…` | | `entities` | array | array | `hd_profile_pic_url_info` fields: | Field | Type | Example | | ----- | ------ | ----------------------------------------- | | `url` | string | `"https://scontent-mia5-2.cdninstagram.…` | ### `POST /api/v1/scrape/instagram/profile-embed` The profile embed HTML, plus an account summary and recent posts. | Field | Type | Required | Default | Description | | -------- | ---- | -------- | ------- | ---------------- | | `handle` | str | **yes** | `—` | Instagram handle | ```bash theme={"system"} curl -X POST https://app.sideshift.app/api/v1/scrape/instagram/profile-embed \ -H 'x-api-key: $SIDESHIFT_SCRAPER_KEY' -H 'Content-Type: application/json' \ -d '{"handle": "nasa"}' ``` **Response** — the `data` object: | Key | Type | | | -------------- | ------- | ----------------------- | | `success` | boolean | Always `true` on a 200. | | `html` | string | | | `profile` | object | | | `recent_posts` | array | | ```json theme={"system"} { "html": "\n\n