> ## 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-08** using the request body shown for that operation. Every example is
required to contain the operation's defining result before it can be published. To keep the reference
readable and safe, arrays show an information-rich item selected from the returned page, 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": {
"user": {
"id": "107955",
"nickname": "TikTok",
"avatarLarger": "https://p16-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/ba67b11de451691939223e9d978e613a~tplv-tiktokx-cropcenter:1080:1080.webp",
"avatarMedium": "https://p16-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/ba67b11de451691939223e9d978e613a~tplv-tiktokx-cropcenter:720:720.webp",
"avatarThumb": "https://p16-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/ba67b11de451691939223e9d978e613a~tplv-tiktokx-cropcenter:100:100.webp",
"secUid": "MS4wLjABAAAAv7iSuuXDJGDvJkmH_vz1qkDZYo1apxgzaxdBSeIuPiM",
"signature": "One TikTok can make a big impact",
"uniqueId": "tiktok",
"UserStoryStatus": 0,
"createTime": 1425144149,
"ftc": false,
"isADVirtual": false,
"isUnderAge18": false,
"openFavorite": false,
"privateAccount": false,
"relation": 0,
"secret": false,
"verified": true,
"bioLink": {
"link": "linktr.ee/tiktok"
},
"ins_id": "",
"twitter_id": "",
"youtube_channel_id": "",
"youtube_channel_title": "",
"commentSetting": null,
"duetSetting": null,
"stitchSetting": null
},
"stats": {
"followerCount": 95152146,
"followingCount": 0,
"heart": 462528210,
"heartCount": 462528210,
"videoCount": 1570,
"diggCount": null
},
"itemList": []
},
"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. A table type such as `string or null` means the
platform can omit that value for some records; the live example never substitutes a default.
Read [Responses and data](/scraper/responses) for
the envelope, identifier, media URL, and nullability rules.
## Billing, pagination, and failures
* The standard cost of every completed platform operation or page is **1 SideShift credit**.
* If your account has negotiated pricing, the Scraper dashboard's **advanced** rate is the exact cost for every operation on this page.
* 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"}
{
"user": {
"id": "107955",
"nickname": "TikTok",
"avatarLarger": "https://p16-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/ba67b11de451691939223e9d978e613a~tplv-tiktokx-cropcenter:1080:1080.webp",
"avatarMedium": "https://p16-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/ba67b11de451691939223e9d978e613a~tplv-tiktokx-cropcenter:720:720.webp",
"avatarThumb": "https://p16-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/ba67b11de451691939223e9d978e613a~tplv-tiktokx-cropcenter:100:100.webp",
"secUid": "MS4wLjABAAAAv7iSuuXDJGDvJkmH_vz1qkDZYo1apxgzaxdBSeIuPiM",
"signature": "One TikTok can make a big impact",
"uniqueId": "tiktok",
"UserStoryStatus": 0,
"createTime": 1425144149,
"ftc": false,
"isADVirtual": false,
"isUnderAge18": false,
"openFavorite": false,
"privateAccount": false,
"relation": 0,
"secret": false,
"verified": true,
"bioLink": {
"link": "linktr.ee/tiktok"
},
"ins_id": "",
"twitter_id": "",
"youtube_channel_id": "",
"youtube_channel_title": "",
"commentSetting": null,
"duetSetting": null,
"stitchSetting": null
},
"stats": {
"followerCount": 95152146,
"followingCount": 0,
"heart": 462528210,
"heartCount": 462528210,
"videoCount": 1570,
"diggCount": null
},
"itemList": []
}
```
`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` | string or null | |
| `duetSetting` | string or null | |
| `stitchSetting` | string or 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` | number or 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` | string or null | Echo of what you queried. |
```json theme={"system"}
{
"unique_id": "ramiryatebyalybly",
"cursor": "1781353841000000",
"has_more": true,
"aweme_list": [
{
"aweme_id": "7659413529019026709",
"desc": "👌😂😜 #друзья #гости #прикол",
"url": "https://www.tiktok.com/@nastenchik__ru/video/7659413529019026709",
"create_time": 1783346188,
"music": {
"author": "NIKITA",
"id": "6709404227262760961",
"title": "Francuzskiy Poceluy",
"album": "Mashina - Special Edition",
"id_str": "6709404227262760961",
"mid": "6709404227262760961",
"owner_nickname": "NIKITA",
"duration": 60,
"is_original": false,
"is_original_sound": false,
"cover_large": {
"uri": "https://p16-common.tiktokcdn-us.com/tos-alisg-v-2774/oUjAIGKLeIAZBmAAUN1xPeImCyNzGepFA7ekcj~tplv-tiktokx-cropcenter:720:720.jpeg",
"url_list": [
"https://p16-common.tiktokcdn-us.com/tos-alisg-v-2774/oUjAIGKLeIAZBmAAUN1xPeImCyNzGepFA7ekcj~tplv-tiktokx-cropcenter:720:720.jpeg"
]
},
"cover_medium": {
"uri": "https://p16-common.tiktokcdn-us.com/tos-alisg-v-2774/oUjAIGKLeIAZBmAAUN1xPeImCyNzGepFA7ekcj~tplv-tiktokx-cropcenter:720:720.jpeg",
"url_list": [
"https://p16-common.tiktokcdn-us.com/tos-alisg-v-2774/oUjAIGKLeIAZBmAAUN1xPeImCyNzGepFA7ekcj~tplv-tiktokx-cropcenter:720:720.jpeg"
]
},
"cover_thumb": {
"uri": "https://p16-common.tiktokcdn-us.com/tos-alisg-v-2774/oUjAIGKLeIAZBmAAUN1xPeImCyNzGepFA7ekcj~tplv-tiktokx-cropcenter:720:720.jpeg",
"url_list": [
"https://p16-common.tiktokcdn-us.com/tos-alisg-v-2774/oUjAIGKLeIAZBmAAUN1xPeImCyNzGepFA7ekcj~tplv-tiktokx-cropcenter:720:720.jpeg"
]
},
"play_url": {
"uri": "https://sf16.tiktokcdn-us.com/obj/tos-alisg-ve-2774/o4bmAZ3CBdBDDwgYW2nVQjoNwQrirCZnAeGtfK",
"url_list": [
"https://sf16.tiktokcdn-us.com/obj/tos-alisg-ve-2774/o4bmAZ3CBdBDDwgYW2nVQjoNwQrirCZnAeGtfK"
]
}
},
"video": {
"data_size": 408118,
"watermark_data_size": 1106239,
"cover": {
"uri": "https://p19-common-sign.tiktokcdn-us.com/tos-alisg-p-0037/ocU0kJ0ejUI30oDfCiGuagL2LEelAAvgvF0UgI~tplv-tiktokx-cropcenter-q:300:400:q70.jpeg",
"url_list": [
"https://p19-common-sign.tiktokcdn-us.com/tos-alisg-p-0037/ocU0kJ0ejUI30oDfCiGuagL2LEelAAvgvF0UgI~tplv-tiktokx-cropcenter-q:300:400:q70.jpeg"
]
},
"download_addr": {
"uri": "https://v45.tiktokcdn-us.com/90a2d60b9b169af605c531a31fac52ed/6a76e640/video/tos/alisg/tos-alisg-pve-0037c001/oc7ENCFSaQDyE3gAQaHgfyE3qXI2ReRBUCC7aB/",
"url_list": [
"https://v45.tiktokcdn-us.com/90a2d60b9b169af605c531a31fac52ed/6a76e640/video/tos/alisg/tos-alisg-pve-0037c001/oc7ENCFSaQDyE3gAQaHgfyE3qXI2ReRBUCC7aB/"
]
},
"dynamic_cover": {
"uri": "https://p16-common-sign.tiktokcdn-us.com/tos-alisg-p-0037/oc2LBa7muVPEBkxiu5BN7tYtBBIaAiI0ABCAI~tplv-tiktokx-origin.image",
"url_list": [
"https://p16-common-sign.tiktokcdn-us.com/tos-alisg-p-0037/oc2LBa7muVPEBkxiu5BN7tYtBBIaAiI0ABCAI~tplv-tiktokx-origin.image"
]
},
"origin_cover": {
"uri": "https://p19-common-sign.tiktokcdn-us.com/tos-alisg-p-0037/o0IaLkt8iPZiuEBIA7INAEBd0Yt7BBO5NBmbV~tplv-tiktokx-shrink-aq:360:360:q75.jpeg",
"url_list": [
"https://p19-common-sign.tiktokcdn-us.com/tos-alisg-p-0037/o0IaLkt8iPZiuEBIA7INAEBd0Yt7BBO5NBmbV~tplv-tiktokx-shrink-aq:360:360:q75.jpeg"
]
},
"play_addr": {
"uri": "https://v45.tiktokcdn-us.com/2ada7b9464e20e093ec46935aaecd0a5/6a76e640/video/tos/alisg/tos-alisg-pve-0037c001/owaGBRkZu5BxiBHIO0L7IA7NEmtEAPiYoVtBj/",
"url_list": [
"https://v45.tiktokcdn-us.com/2ada7b9464e20e093ec46935aaecd0a5/6a76e640/video/tos/alisg/tos-alisg-pve-0037c001/owaGBRkZu5BxiBHIO0L7IA7NEmtEAPiYoVtBj/"
]
}
},
"author": {
"nickname": "@nastenchik__ru",
"unique_id": "nastenchik__ru",
"region": "BY",
"uid": "6615520580681973766",
"avatar_larger": {
"uri": "https://p19-common-sign.tiktokcdn-us.com/tos-alisg-avt-0068/9959bbd48536962fcc479354dfe12a23~tplv-tiktokx-cropcenter-q:300:300:q70.jpeg",
"url_list": [
"https://p19-common-sign.tiktokcdn-us.com/tos-alisg-avt-0068/9959bbd48536962fcc479354dfe12a23~tplv-tiktokx-cropcenter-q:300:300:q70.jpeg"
]
},
"avatar_medium": {
"uri": "https://p19-common-sign.tiktokcdn-us.com/tos-alisg-avt-0068/9959bbd48536962fcc479354dfe12a23~tplv-tiktokx-cropcenter-q:300:300:q70.jpeg",
"url_list": [
"https://p19-common-sign.tiktokcdn-us.com/tos-alisg-avt-0068/9959bbd48536962fcc479354dfe12a23~tplv-tiktokx-cropcenter-q:300:300:q70.jpeg"
]
},
"avatar_thumb": {
"uri": "https://p19-common-sign.tiktokcdn-us.com/tos-alisg-avt-0068/9959bbd48536962fcc479354dfe12a23~tplv-tiktokx-cropcenter-q:300:300:q70.jpeg",
"url_list": [
"https://p19-common-sign.tiktokcdn-us.com/tos-alisg-avt-0068/9959bbd48536962fcc479354dfe12a23~tplv-tiktokx-cropcenter-q:300:300:q70.jpeg"
]
}
},
"statistics": {
"aweme_id": "7659413529019026709",
"collect_count": 12279,
"comment_count": 433,
"play_count": 2052779,
"share_count": 87796,
"digg_count": 281369,
"download_count": 2170
},
"author_user_id": "6615520580681973766",
"create_time_utc": "2026-07-06T13:56:28.000Z",
"media_id": "v14044g50000d95r817og65rtu92dd6g",
"region": "BY",
"aweme_type": 0,
"is_ad": false,
"is_nff_or_nr": false,
"is_top": 0,
"item_comment_settings": 0,
"anchors": [
{
"id": "7658297519461449744",
"component_key": "anchor_ucg_template",
"description": "Templates",
"extra": "{\"dispatch_type\":\"ugc_template\",\"origin_video_id\":\"7658297510980766997\",\"tags\":\"\",\"music_post_unavailable\":\"false\",\"icon\":\"https://lf16-effectcdn-us.tiktokcdn-us.com/obj/ies-material-resource-us/2169d26df2f0ccc1e5ba488cb1be1ff0\",\"title\":\"\",\"sub_type\":\"ugc\",\"author_id\":\"6752985…",
"keyword": "Try TikTok template",
"log_extra": "{\"anchor_id\":\"7658297519461449744\",\"anchor_name\":\"Try TikTok template\",\"anchor_type\":\"ugc_template\",\"has_friends_info\":\"0\"}",
"type": 65,
"actions": [
{
"schema": "shoot",
"action_type": 1,
"icon": {
"uri": "tiktok-obj/28px_primary_create_onDark3x.png",
"height": 720,
"width": 720,
"url_list": [
"https://p16-common.tiktokcdn-us.com/tiktok-obj/28px_primary_create_onDark3x.png~tplv-tiktokx-origin.image",
"https://p19-common.tiktokcdn-us.com/tiktok-obj/28px_primary_create_onDark3x.png~tplv-tiktokx-origin.image",
"https://p16-common.tiktokcdn-us.com/tiktok-obj/28px_primary_create_onDark3x.png~tplv-tiktokx-origin.jpeg"
]
}
}
],
"icon": {
"uri": "tiktok-obj/Templates_Cards.png",
"height": 720,
"width": 720,
"url_list": [
"https://p16-common.tiktokcdn-us.com/tiktok-obj/Templates_Cards.png~tplv-tiktokx-origin.image",
"https://p19-common.tiktokcdn-us.com/tiktok-obj/Templates_Cards.png~tplv-tiktokx-origin.image",
"https://p16-common.tiktokcdn-us.com/tiktok-obj/Templates_Cards.png~tplv-tiktokx-origin.jpeg"
]
},
"thumbnail": {
"uri": "tiktok-obj/Templates_Cards.png",
"height": 720,
"width": 720,
"url_list": [
"https://p16-common.tiktokcdn-us.com/tiktok-obj/Templates_Cards.png~tplv-tiktokx-origin.image",
"https://p19-common.tiktokcdn-us.com/tiktok-obj/Templates_Cards.png~tplv-tiktokx-origin.image",
"https://p16-common.tiktokcdn-us.com/tiktok-obj/Templates_Cards.png~tplv-tiktokx-origin.jpeg"
]
}
}
],
"commerce_info": {
"bc_label_test_text": "Promotional content",
"adv_promotable": true,
"auction_ad_invited": false,
"brand_organic_type": 1010,
"branded_content_type": 0,
"is_diversion_ad": 0,
"with_comment_filter_words": false
}
}
],
"user_id": null
}
```
### `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` | string or null | Echo of what you queried. |
```json theme={"system"}
{
"unique_id": "tiktok",
"cursor": "30",
"has_more": true,
"aweme_list": [
{
"aweme_id": "7647625121582025998",
"desc": "what an experience 🥹 full vid coming soon 👀 #disclosureday",
"url": "https://www.tiktok.com/@tiktokcreators/video/7647625121582025998",
"create_time": 1780601491,
"music": {
"author": "dhiesusongko",
"id": "7495774126525745926",
"title": "original sound - dhiesusongko",
"id_str": "7495774126525745926",
"mid": "7495774126525745926",
"owner_nickname": "dhiesusongko",
"duration": 15,
"is_original": true,
"is_original_sound": true,
"cover_large": {
"uri": "https://p16-common-sign.tiktokcdn-us.com/tos-alisg-avt-0068/7329951427051126802~tplv-tiktokx-cropcenter:1080:1080.jpeg",
"url_list": [
"https://p16-common-sign.tiktokcdn-us.com/tos-alisg-avt-0068/7329951427051126802~tplv-tiktokx-cropcenter:1080:1080.jpeg"
]
},
"cover_medium": {
"uri": "https://p16-common-sign.tiktokcdn-us.com/tos-alisg-avt-0068/7329951427051126802~tplv-tiktokx-cropcenter:1080:1080.jpeg",
"url_list": [
"https://p16-common-sign.tiktokcdn-us.com/tos-alisg-avt-0068/7329951427051126802~tplv-tiktokx-cropcenter:1080:1080.jpeg"
]
},
"cover_thumb": {
"uri": "https://p16-common-sign.tiktokcdn-us.com/tos-alisg-avt-0068/7329951427051126802~tplv-tiktokx-cropcenter:1080:1080.jpeg",
"url_list": [
"https://p16-common-sign.tiktokcdn-us.com/tos-alisg-avt-0068/7329951427051126802~tplv-tiktokx-cropcenter:1080:1080.jpeg"
]
},
"play_url": {
"uri": "https://v19-ies-music.tiktokcdn-us.com/cdfe7b6f3e78d1153fc270b23b73b97d/6a7fcce6/video/tos/useast2a/tos-useast2a-v-27dcd7/o0SY5B0A0vkCi6MaW8ZJXlQ0iimVXUDAnISK6/",
"url_list": [
"https://v19-ies-music.tiktokcdn-us.com/cdfe7b6f3e78d1153fc270b23b73b97d/6a7fcce6/video/tos/useast2a/tos-useast2a-v-27dcd7/o0SY5B0A0vkCi6MaW8ZJXlQ0iimVXUDAnISK6/"
]
}
},
"video": {
"data_size": 2804008,
"duration": 15,
"watermark_data_size": 2644716,
"cover": {
"uri": "https://p16-common-sign.tiktokcdn-us.com/tos-useast5-p-0068-tx/oI4U0OWFBIgp5h2gA2iDpPIgmAfK1XBIipwgCE~tplv-tiktokx-cropcenter-q:300:400:q70.jpeg",
"url_list": [
"https://p16-common-sign.tiktokcdn-us.com/tos-useast5-p-0068-tx/oI4U0OWFBIgp5h2gA2iDpPIgmAfK1XBIipwgCE~tplv-tiktokx-cropcenter-q:300:400:q70.jpeg"
]
},
"download_addr": {
"uri": "https://v16m.tiktokcdn-us.com/237088c5e8506d11a0845df5141b3dfd/6a76e64a/video/tos/useast5/tos-useast5-pve-0068-tx/o4dLSFDzREDe6ICBcDEQABBApgtgTsFpIqfyNx/",
"url_list": [
"https://v16m.tiktokcdn-us.com/237088c5e8506d11a0845df5141b3dfd/6a76e64a/video/tos/useast5/tos-useast5-pve-0068-tx/o4dLSFDzREDe6ICBcDEQABBApgtgTsFpIqfyNx/"
]
},
"dynamic_cover": {
"uri": "https://p19-common-sign.tiktokcdn-us.com/tos-useast5-p-0068-tx/oYm201IYfAAlBgBgCpxhgFIwUiIVOENd2piIB5~tplv-tiktokx-origin.image",
"url_list": [
"https://p19-common-sign.tiktokcdn-us.com/tos-useast5-p-0068-tx/oYm201IYfAAlBgBgCpxhgFIwUiIVOENd2piIB5~tplv-tiktokx-origin.image"
]
},
"origin_cover": {
"uri": "https://p16-common-sign.tiktokcdn-us.com/tos-useast5-p-0068-tx/osg0pBV51kBD3mUhA2iiwgBgCEAIvVqIIFf2pO~tplv-tiktokx-shrink-aq:360:360:q75.webp",
"url_list": [
"https://p16-common-sign.tiktokcdn-us.com/tos-useast5-p-0068-tx/osg0pBV51kBD3mUhA2iiwgBgCEAIvVqIIFf2pO~tplv-tiktokx-shrink-aq:360:360:q75.webp"
]
},
"play_addr": {
"uri": "https://v16m.tiktokcdn-us.com/cb54d9183164f2ecef262e65dcdfa37f/6a76e64a/video/tos/useast5/tos-useast5-ve-0068c003-tx/o41rplhFgAmIOAiI2B2EgqFQCECUwufIdg0Bi5/",
"url_list": [
"https://v16m.tiktokcdn-us.com/cb54d9183164f2ecef262e65dcdfa37f/6a76e64a/video/tos/useast5/tos-useast5-ve-0068c003-tx/o41rplhFgAmIOAiI2B2EgqFQCECUwufIdg0Bi5/"
]
}
},
"author": {
"nickname": "tiktok creators",
"unique_id": "tiktokcreators",
"region": "US",
"uid": "6551237489917432832",
"avatar_larger": {
"uri": "https://p19-common-sign.tiktokcdn-us.com/tos-maliva-avt-0068/7310199914919673862~tplv-tiktokx-cropcenter:300:300.jpeg",
"url_list": [
"https://p19-common-sign.tiktokcdn-us.com/tos-maliva-avt-0068/7310199914919673862~tplv-tiktokx-cropcenter:300:300.jpeg"
]
},
"avatar_medium": {
"uri": "https://p19-common-sign.tiktokcdn-us.com/tos-maliva-avt-0068/7310199914919673862~tplv-tiktokx-cropcenter:300:300.jpeg",
"url_list": [
"https://p19-common-sign.tiktokcdn-us.com/tos-maliva-avt-0068/7310199914919673862~tplv-tiktokx-cropcenter:300:300.jpeg"
]
},
"avatar_thumb": {
"uri": "https://p19-common-sign.tiktokcdn-us.com/tos-maliva-avt-0068/7310199914919673862~tplv-tiktokx-cropcenter:300:300.jpeg",
"url_list": [
"https://p19-common-sign.tiktokcdn-us.com/tos-maliva-avt-0068/7310199914919673862~tplv-tiktokx-cropcenter:300:300.jpeg"
]
}
},
"statistics": {
"aweme_id": "7647625121582025998",
"collect_count": 484,
"comment_count": 507,
"play_count": 193617,
"share_count": 327,
"digg_count": 5256,
"download_count": 25
},
"author_user_id": "6551237489917432832",
"create_time_utc": "2026-06-04T19:31:31.000Z",
"media_id": "v12044gd0000d8gt0gfog65m2o2jd6sg",
"region": "US",
"aweme_type": 0,
"is_ad": false,
"is_nff_or_nr": false,
"is_top": 0,
"item_comment_settings": 0,
"anchors": [
{
"id": "7634950575239596039",
"component_key": "anchor_movie_tok",
"description": "2026",
"extra": "{\"extra_info\":\"{\\\"promotion_entity_id\\\":\\\"7620936042547249164\\\",\\\"basic_info\\\":{\\\"ip_title\\\":\\\"Disclosure Day\\\",\\\"plot\\\":\\\"If you found out we weren’t alone, if someone showed you, proved it to you, would that frighten you? This summer, the truth belongs to eight billion peopl…",
"keyword": "Movie · Disclosure Day",
"log_extra": "{\"anchor_id\":\"7634950575239596039\",\"anchor_name\":\"Disclosure Day\",\"anchor_type\":\"movie\"}",
"schema": "aweme://lynxview?disable_bounce=1&hide_nav_bar=1&should_full_screen=1&use_forest=1&use_spark=1&url=https%3A%2F%2Flf16-gecko-source.tiktokcdn-us.com%2Fobj%2Fbyte-gurd-source-tx%2F10%2Fgecko%2Fresource%2Ftiktok_ogc_promotion_lynx%2Fpages%2Fmovie_anchor_landing%2Ftemplate.js&use_…",
"general_type": 1,
"type": 61,
"icon": {
"uri": "tiktok-obj/anchor_movietok.png",
"height": 720,
"width": 720,
"url_list": [
"https://p19-common.tiktokcdn-us.com/tiktok-obj/anchor_movietok.png~tplv-tiktokx-origin.image",
"https://p16-common.tiktokcdn-us.com/tiktok-obj/anchor_movietok.png~tplv-tiktokx-origin.image",
"https://p19-common.tiktokcdn-us.com/tiktok-obj/anchor_movietok.png~tplv-tiktokx-origin.jpeg"
]
},
"thumbnail": {
"uri": "https://p16-common-sign.tiktokcdn-us.com/tos-useast8-i-bqyoymiyqj-tx2/96c840b84cec463cb35a34189a6c27dd~tplv-bqyoymiyqj-ma-thumbnail.heic",
"height": 720,
"width": 720,
"url_list": [
"https://p16-common-sign.tiktokcdn-us.com/tos-useast8-i-bqyoymiyqj-tx2/96c840b84cec463cb35a34189a6c27dd~tplv-bqyoymiyqj-ma-thumbnail.heic"
]
}
}
],
"commerce_info": {
"adv_promotable": false,
"auction_ad_invited": false,
"branded_content_type": 0,
"is_diversion_ad": 0,
"with_comment_filter_words": false
}
}
],
"user_id": null
}
```
### `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 '{"handle":"nasa","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` | string or null | Pass back on the next call. `null` once the list is exhausted. |
| `has_more` | boolean | Whether another page exists. |
| `unique_id` | string or null | Echo of what you queried. |
| `user_id` | string | Echo of what you queried. |
```json theme={"system"}
{
"unique_id": "nasa",
"user_id": "7664638705177150477",
"has_more": false,
"aweme_list": [
{
"aweme_id": "7671359229290106125",
"url": "https://www.tiktok.com/@nasa/video/7671359229290106125",
"create_time": 1786127533,
"music": {
"author": "NASA",
"id": "7671356189888367374",
"title": "original sound - nasa",
"id_str": "7671356189888367374",
"mid": "7671356189888367374",
"owner_nickname": "NASA",
"duration": 95,
"is_original": true,
"is_original_sound": true,
"cover_large": {
"uri": "https://p19-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/e5143212a59c09a008bf50f487d54d1f~tplv-tiktokx-cropcenter-q:1080:1080:q70.webp",
"url_list": [
"https://p19-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/e5143212a59c09a008bf50f487d54d1f~tplv-tiktokx-cropcenter-q:1080:1080:q70.webp"
]
},
"cover_medium": {
"uri": "https://p19-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/e5143212a59c09a008bf50f487d54d1f~tplv-tiktokx-cropcenter-q:1080:1080:q70.webp",
"url_list": [
"https://p19-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/e5143212a59c09a008bf50f487d54d1f~tplv-tiktokx-cropcenter-q:1080:1080:q70.webp"
]
},
"cover_thumb": {
"uri": "https://p19-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/e5143212a59c09a008bf50f487d54d1f~tplv-tiktokx-cropcenter-q:1080:1080:q70.webp",
"url_list": [
"https://p19-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/e5143212a59c09a008bf50f487d54d1f~tplv-tiktokx-cropcenter-q:1080:1080:q70.webp"
]
},
"play_url": {
"uri": "https://v19-ies-music.tiktokcdn-eu.com/fbf2a94f53b3c409283c5236ec0094db/6a7fcd1a/video/tos/alisg/tos-alisg-v-2370c799-sg/owEA21GKFAxAWwEM7REBBiiBDIBrAOAMaf8pdp/",
"url_list": [
"https://v19-ies-music.tiktokcdn-eu.com/fbf2a94f53b3c409283c5236ec0094db/6a7fcd1a/video/tos/alisg/tos-alisg-v-2370c799-sg/owEA21GKFAxAWwEM7REBBiiBDIBrAOAMaf8pdp/"
]
}
},
"video": {
"data_size": 7240418,
"duration": 95,
"watermark_data_size": 6869260,
"cover": {
"uri": "https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/oYjJKA141dBp5md2A1iiwJBUCOAIh2MIEDfjpx~tplv-tiktokx-cropcenter-q:300:400:q70.jpeg",
"url_list": [
"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/oYjJKA141dBp5md2A1iiwJBUCOAIh2MIEDfjpx~tplv-tiktokx-cropcenter-q:300:400:q70.jpeg"
]
},
"download_addr": {
"uri": "https://v19.tiktokcdn-eu.com/0a9ae6b0c20227cfdc49656cdfae3b4c/6a77e3bb/video/tos/alisg/tos-alisg-ve-37c799-sg/owigdGICIBAfQER2Q1jwj4DjpAiJmJOBxACUz1/",
"url_list": [
"https://v19.tiktokcdn-eu.com/0a9ae6b0c20227cfdc49656cdfae3b4c/6a77e3bb/video/tos/alisg/tos-alisg-ve-37c799-sg/owigdGICIBAfQER2Q1jwj4DjpAiJmJOBxACUz1/"
]
},
"dynamic_cover": {
"uri": "https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/owAaBCK1piUArIWIJ42fAiJOxBK5DxI1mXjdjw~tplv-tiktokx-origin.image",
"url_list": [
"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/owAaBCK1piUArIWIJ42fAiJOxBK5DxI1mXjdjw~tplv-tiktokx-origin.image"
]
},
"origin_cover": {
"uri": "https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/ow241iAIpB1NOdCJJwrjA1KjIfmUD4Bi2RI2xA~tplv-tiktokx-shrink-aq:360:360:q75.webp",
"url_list": [
"https://p16-common-sign.tiktokcdn-eu.com/tos-useast5-p-0068-tx/ow241iAIpB1NOdCJJwrjA1KjIfmUD4Bi2RI2xA~tplv-tiktokx-shrink-aq:360:360:q75.webp"
]
},
"play_addr": {
"uri": "https://v19.tiktokcdn-eu.com/8e8ae609f2b59d94ac0e805bc42cb990/6a77e3bb/video/tos/alisg/tos-alisg-ve-37c799-sg/oEDjIPA1Bw5EB5I4GidOfQmA2UiBOi1JxpjJdC/",
"url_list": [
"https://v19.tiktokcdn-eu.com/8e8ae609f2b59d94ac0e805bc42cb990/6a77e3bb/video/tos/alisg/tos-alisg-ve-37c799-sg/oEDjIPA1Bw5EB5I4GidOfQmA2UiBOi1JxpjJdC/"
]
}
},
"author": {
"nickname": "NASA",
"unique_id": "nasa",
"region": "US",
"uid": "7664638705177150477",
"avatar_larger": {
"uri": "https://p19-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/e5143212a59c09a008bf50f487d54d1f~tplv-tiktokx-cropcenter-q:300:300:q70.webp",
"url_list": [
"https://p19-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/e5143212a59c09a008bf50f487d54d1f~tplv-tiktokx-cropcenter-q:300:300:q70.webp"
]
},
"avatar_medium": {
"uri": "https://p19-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/e5143212a59c09a008bf50f487d54d1f~tplv-tiktokx-cropcenter-q:300:300:q70.webp",
"url_list": [
"https://p19-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/e5143212a59c09a008bf50f487d54d1f~tplv-tiktokx-cropcenter-q:300:300:q70.webp"
]
},
"avatar_thumb": {
"uri": "https://p19-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/e5143212a59c09a008bf50f487d54d1f~tplv-tiktokx-cropcenter-q:300:300:q70.webp",
"url_list": [
"https://p19-common-sign.tiktokcdn-eu.com/tos-maliva-avt-0068/e5143212a59c09a008bf50f487d54d1f~tplv-tiktokx-cropcenter-q:300:300:q70.webp"
]
}
},
"statistics": {
"aweme_id": "7671359229290106125",
"collect_count": 0,
"comment_count": 0,
"play_count": 23647,
"share_count": 35,
"digg_count": 2189,
"download_count": 1
},
"author_user_id": "7664638705177150477",
"create_time_utc": "2026-08-07T18:32:13.000Z",
"media_id": "v12044gd0000d9r29afog65l1orm76s0",
"region": "US",
"aweme_type": 0,
"is_ad": false,
"is_nff_or_nr": false,
"is_top": 0,
"item_comment_settings": 3,
"commerce_info": {
"adv_promotable": false,
"auction_ad_invited": false,
"branded_content_type": 0,
"is_diversion_ad": 0,
"with_comment_filter_words": false
}
}
],
"cursor": null
}
```
### `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"}
{
"unique_id": "tiktok",
"min_time": "1786155364",
"user_id": "107955",
"has_more": true,
"total": 95154007,
"followers": [
{
"nickname": "Y_707✪🪖",
"unique_id": ".rl_65",
"region": "SA",
"sec_uid": "MS4wLjABAAAAv9-Fj3vCZBokgj-w6a8k4BlnE7xY4c3zBm-WJOS_3_K7oz1AwUqxhzLLfiYb3nTR",
"signature": "كلمتان خفيفة على الليسان ثقيلاتان في الميزان حبيبتان على الرحمان سبحان الله وبحمده سبحان الله العظيم",
"uid": "7386510437666718737",
"aweme_count": 2,
"favoriting_count": 874,
"follower_count": 26,
"following_count": 314,
"secret": false,
"total_favorited": 38,
"verified": false,
"avatar_larger": {
"uri": "https://p16-common-sign.tiktokcdn-us.com/tos-alisg-avt-0068/eb9b02a516f2a9168f1017961cc19ae6~tplv-tiktokx-cropcenter:300:300.jpeg",
"url_list": [
"https://p16-common-sign.tiktokcdn-us.com/tos-alisg-avt-0068/eb9b02a516f2a9168f1017961cc19ae6~tplv-tiktokx-cropcenter:300:300.jpeg"
]
},
"avatar_medium": {
"uri": "https://p16-common-sign.tiktokcdn-us.com/tos-alisg-avt-0068/eb9b02a516f2a9168f1017961cc19ae6~tplv-tiktokx-cropcenter:300:300.jpeg",
"url_list": [
"https://p16-common-sign.tiktokcdn-us.com/tos-alisg-avt-0068/eb9b02a516f2a9168f1017961cc19ae6~tplv-tiktokx-cropcenter:300:300.jpeg"
]
},
"avatar_thumb": {
"uri": "https://p16-common-sign.tiktokcdn-us.com/tos-alisg-avt-0068/eb9b02a516f2a9168f1017961cc19ae6~tplv-tiktokx-cropcenter:300:300.jpeg",
"url_list": [
"https://p16-common-sign.tiktokcdn-us.com/tos-alisg-avt-0068/eb9b02a516f2a9168f1017961cc19ae6~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` | string or 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"}
{
"unique_id": "tiktok",
"user_id": "107955",
"has_more": false,
"total": 2,
"followings": [
{
"nickname": "tiktok creators",
"unique_id": "tiktokcreators",
"region": "US",
"sec_uid": "MS4wLjABAAAAXqqA-cLDC0hfQPIrS5APYNsg04zkl-socWCkqkI3UIOaEe6_Qnokg0GcWpLnMNQP",
"signature": "The official account for TikTok Creators who inspire creativity and bring joy ✨\n\n⬇️ Creator Programs 💰⬇️",
"uid": "6551237489917432832",
"aweme_count": 1096,
"favoriting_count": 1865,
"follower_count": 8610659,
"following_count": 569,
"secret": false,
"total_favorited": 33349621,
"verified": true,
"avatar_larger": {
"uri": "https://p19-common-sign.tiktokcdn.com/tos-maliva-avt-0068/7310199914919673862~tplv-tiktokx-cropcenter-q:300:300:q70.webp",
"url_list": [
"https://p19-common-sign.tiktokcdn.com/tos-maliva-avt-0068/7310199914919673862~tplv-tiktokx-cropcenter-q:300:300:q70.webp"
]
},
"avatar_medium": {
"uri": "https://p19-common-sign.tiktokcdn.com/tos-maliva-avt-0068/7310199914919673862~tplv-tiktokx-cropcenter-q:300:300:q70.webp",
"url_list": [
"https://p19-common-sign.tiktokcdn.com/tos-maliva-avt-0068/7310199914919673862~tplv-tiktokx-cropcenter-q:300:300:q70.webp"
]
},
"avatar_thumb": {
"uri": "https://p19-common-sign.tiktokcdn.com/tos-maliva-avt-0068/7310199914919673862~tplv-tiktokx-cropcenter-q:300:300:q70.webp",
"url_list": [
"https://p19-common-sign.tiktokcdn.com/tos-maliva-avt-0068/7310199914919673862~tplv-tiktokx-cropcenter-q:300:300:q70.webp"
]
}
}
],
"min_time": null
}
```
### `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":"7465426882822883344"}'
```
**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,
"music_info": {
"author": "ktmelodies",
"id": "7465426882822883344",
"title": "summer like this",
"album": "summer like this",
"id_str": "7465426882822883344",
"mid": "7465426882822883344",
"owner_nickname": "ktmelodies",
"duration": 60,
"is_original": false,
"is_original_sound": false,
"user_count": 566,
"cover_large": {
"uri": "https://p16-sg.tiktokcdn.com/aweme/200x200/tos-alisg-v-2774/oYwEhwYAWiZ1B5iFMzr6AECqjAKAUpPACAaR5.jpeg",
"url_list": [
"https://p16-sg.tiktokcdn.com/aweme/200x200/tos-alisg-v-2774/oYwEhwYAWiZ1B5iFMzr6AECqjAKAUpPACAaR5.jpeg"
]
},
"cover_medium": {
"uri": "https://p16-sg.tiktokcdn.com/aweme/200x200/tos-alisg-v-2774/oYwEhwYAWiZ1B5iFMzr6AECqjAKAUpPACAaR5.jpeg",
"url_list": [
"https://p16-sg.tiktokcdn.com/aweme/200x200/tos-alisg-v-2774/oYwEhwYAWiZ1B5iFMzr6AECqjAKAUpPACAaR5.jpeg"
]
},
"cover_thumb": {
"uri": "https://p16-sg.tiktokcdn.com/aweme/200x200/tos-alisg-v-2774/oYwEhwYAWiZ1B5iFMzr6AECqjAKAUpPACAaR5.jpeg",
"url_list": [
"https://p16-sg.tiktokcdn.com/aweme/200x200/tos-alisg-v-2774/oYwEhwYAWiZ1B5iFMzr6AECqjAKAUpPACAaR5.jpeg"
]
},
"play_url": {
"uri": "https://sf16-ies-music-sg.tiktokcdn.com/obj/tos-alisg-ve-2774/oULjFO1JzyAE2FuaAwiiwYBnWzBssIlMIjf0oU",
"url_list": [
"https://sf16-ies-music-sg.tiktokcdn.com/obj/tos-alisg-ve-2774/oULjFO1JzyAE2FuaAwiiwYBnWzBssIlMIjf0oU"
]
}
},
"status_msg": "",
"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` | string or 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":"7465426882822883344","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` | string or null | Platform tracing block. Always `null` here. |
| `log_pb` | object or 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"}
{
"cursor": "12",
"music_id": "7465426882822883344",
"can_pin_video": false,
"has_more": true,
"need_lazy_loading": false,
"status_code": 0,
"aweme_list": [
{
"aweme_id": "7540649617801710879",
"desc": "Todavía no me lo creoo 🥹❤️🩹 #girliesdelsur #gym #Fitness #walk #run #girlies #girls",
"url": "https://www.tiktok.com/@kayra.rc/video/7540649617801710879",
"create_time": 1755694316,
"video": {
"data_size": 5423848,
"duration": 15,
"watermark_data_size": 5511051,
"cover": {
"uri": "https://p16-common-sign.tiktokcdn.com/tos-useast8-p-0068-tx2/oAN6CAliIKVfTJC6xAAusIAUEAI0p3BaL1OiiB~tplv-tiktokx-cropcenter-q:300:400:q70.webp",
"url_list": [
"https://p16-common-sign.tiktokcdn.com/tos-useast8-p-0068-tx2/oAN6CAliIKVfTJC6xAAusIAUEAI0p3BaL1OiiB~tplv-tiktokx-cropcenter-q:300:400:q70.webp"
]
},
"download_addr": {
"uri": "https://v31-jp.tiktokcdn.com/a2ccbceba65d8e41948700f43f4019a8/6a77e36f/video/tos/alisg/tos-alisg-ve-37c799-sg/o4WICQggiiADPUQAEIiBqdCluuxFI80lMiSfAQ/",
"url_list": [
"https://v31-jp.tiktokcdn.com/a2ccbceba65d8e41948700f43f4019a8/6a77e36f/video/tos/alisg/tos-alisg-ve-37c799-sg/o4WICQggiiADPUQAEIiBqdCluuxFI80lMiSfAQ/"
]
},
"dynamic_cover": {
"uri": "https://p16-common-sign.tiktokcdn.com/tos-useast8-p-0068-tx2/oAN6CAliIKVfTJC6xAAusIAUEAI0p3BaL1OiiB~tplv-tiktokx-origin.image",
"url_list": [
"https://p16-common-sign.tiktokcdn.com/tos-useast8-p-0068-tx2/oAN6CAliIKVfTJC6xAAusIAUEAI0p3BaL1OiiB~tplv-tiktokx-origin.image"
]
},
"origin_cover": {
"uri": "https://p19-common-sign.tiktokcdn.com/tos-useast8-p-0068-tx2/o4llusPCIIDAOq4f8OIBSCB0S9giiiduAAuIxU~tplv-tiktokx-shrink-aq:360:360:q75.webp",
"url_list": [
"https://p19-common-sign.tiktokcdn.com/tos-useast8-p-0068-tx2/o4llusPCIIDAOq4f8OIBSCB0S9giiiduAAuIxU~tplv-tiktokx-shrink-aq:360:360:q75.webp"
]
},
"play_addr": {
"uri": "https://v31-jp.tiktokcdn.com/84ec67519e400c0303d25f276e69a965/6a77e36f/video/tos/alisg/tos-alisg-ve-37c799-sg/oYfWgALWsIq3D6fXIAGARhSwjNRAECKIU4IKeU/",
"url_list": [
"https://v31-jp.tiktokcdn.com/84ec67519e400c0303d25f276e69a965/6a77e36f/video/tos/alisg/tos-alisg-ve-37c799-sg/oYfWgALWsIq3D6fXIAGARhSwjNRAECKIU4IKeU/"
]
}
},
"author": {
"nickname": "kayra.rc",
"unique_id": "kayra.rc",
"region": "PR",
"uid": "6930458983154123781",
"avatar_larger": {
"uri": "https://p16-common-sign.tiktokcdn.com/tos-maliva-avt-0068/8ce9e770f4a20eb06617a59cf8009250~tplv-tiktokx-cropcenter-q:300:300:q70.jpeg",
"url_list": [
"https://p16-common-sign.tiktokcdn.com/tos-maliva-avt-0068/8ce9e770f4a20eb06617a59cf8009250~tplv-tiktokx-cropcenter-q:300:300:q70.jpeg"
]
},
"avatar_medium": {
"uri": "https://p16-common-sign.tiktokcdn.com/tos-maliva-avt-0068/8ce9e770f4a20eb06617a59cf8009250~tplv-tiktokx-cropcenter-q:300:300:q70.jpeg",
"url_list": [
"https://p16-common-sign.tiktokcdn.com/tos-maliva-avt-0068/8ce9e770f4a20eb06617a59cf8009250~tplv-tiktokx-cropcenter-q:300:300:q70.jpeg"
]
},
"avatar_thumb": {
"uri": "https://p16-common-sign.tiktokcdn.com/tos-maliva-avt-0068/8ce9e770f4a20eb06617a59cf8009250~tplv-tiktokx-cropcenter-q:300:300:q70.jpeg",
"url_list": [
"https://p16-common-sign.tiktokcdn.com/tos-maliva-avt-0068/8ce9e770f4a20eb06617a59cf8009250~tplv-tiktokx-cropcenter-q:300:300:q70.jpeg"
]
}
},
"statistics": {
"aweme_id": "7540649617801710879",
"collect_count": 57,
"comment_count": 102,
"play_count": 15869,
"share_count": 84,
"digg_count": 943,
"download_count": 3
},
"author_user_id": "6930458983154123781",
"create_time_utc": "2025-08-20T12:51:56.000Z",
"media_id": "v15044gf0000d2is8evog65s1kgabeg0",
"region": "PR",
"aweme_type": 0,
"is_ad": false,
"is_nff_or_nr": false,
"is_top": 0,
"item_comment_settings": 0,
"anchors": [
{
"id": "7540649559165337613",
"component_key": "anchor_ucg_template",
"description": "Templates",
"extra": "{\"music_post_unavailable\":\"false\",\"dispatch_type\":\"ugc_create\",\"origin_video_id\":\"7540649617801710879\",\"tags\":\"\",\"music_id\":\"7465426882822883344\",\"sub_type\":\"ugc\",\"nle_summary\":\"{\\\"slots\\\":\\\"[{\\\\\\\"clip_end\\\\\\\":15.715011596679688,\\\\\\\"clip_start\\\\\\\":0.0,\\\\\\\"description\\\\\\\":\\\\\\\"\\…",
"keyword": "Try TikTok template",
"log_extra": "{\"anchor_id\":\"7540649559165337613\",\"anchor_name\":\"Try TikTok template\",\"anchor_type\":\"ugc_template\",\"has_friends_info\":\"0\"}",
"type": 65,
"actions": [
{
"schema": "shoot",
"action_type": 1,
"icon": {
"uri": "tiktok-obj/28px_primary_create_onDark3x.png",
"height": 720,
"width": 720,
"url_list": [
"https://p19-common.tiktokcdn.com/tiktok-obj/28px_primary_create_onDark3x.png~tplv-tiktokx-origin.image",
"https://p16-common.tiktokcdn.com/tiktok-obj/28px_primary_create_onDark3x.png~tplv-tiktokx-origin.image",
"https://p19-common.tiktokcdn.com/tiktok-obj/28px_primary_create_onDark3x.png~tplv-tiktokx-origin.jpeg"
]
}
}
],
"icon": {
"uri": "tiktok-obj/Templates_Cards.png",
"height": 720,
"width": 720,
"url_list": [
"https://p16-common.tiktokcdn.com/tiktok-obj/Templates_Cards.png~tplv-tiktokx-origin.image",
"https://p19-common.tiktokcdn.com/tiktok-obj/Templates_Cards.png~tplv-tiktokx-origin.image",
"https://p16-common.tiktokcdn.com/tiktok-obj/Templates_Cards.png~tplv-tiktokx-origin.jpeg"
]
},
"thumbnail": {
"uri": "tiktok-obj/Templates_Cards.png",
"height": 720,
"width": 720,
"url_list": [
"https://p16-common.tiktokcdn.com/tiktok-obj/Templates_Cards.png~tplv-tiktokx-origin.image",
"https://p19-common.tiktokcdn.com/tiktok-obj/Templates_Cards.png~tplv-tiktokx-origin.image",
"https://p16-common.tiktokcdn.com/tiktok-obj/Templates_Cards.png~tplv-tiktokx-origin.jpeg"
]
}
}
],
"commerce_info": {
"adv_promotable": false,
"auction_ad_invited": false,
"branded_content_type": 0,
"is_diversion_ad": 0,
"with_comment_filter_words": false
}
}
],
"status_msg": "",
"extra": null,
"log_pb": null
}
```
## 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":"booktok"}'
```
> Accepts `hashtag` (the name) or `challenge_id` (e.g. "229207").
**Response** — the `data` object:
| Key | Type | |
| --------- | ------ | - |
| `hashtag` | object | |
```json theme={"system"}
{
"hashtag": {
"cover_url": "https://p19-common-sign.tiktokcdn.com/tiktok-obj/ffd11355ceddd5cb7a3f7f4a1f059df0.png~tplv-tiktokx-origin.image",
"description": "Calling all book lovers, join the #BookTok Post Contest from April 13th to May 11th for a chance to win $3000! Click here to join: https://vt.tiktok.com/ZSHgdjSGp/",
"hashtag_id": "1622962893630470",
"hashtag_link": "https://www.tiktok.com/tag/BookTok",
"name": "BookTok",
"is_challenge": false,
"is_commerce": false,
"is_pgc_show": false,
"is_strong_music": false,
"post_count": 83697988,
"type": 2,
"view_count": 540703740020
}
}
```
`hashtag` fields:
| Field | Type | Example |
| ----------------- | -------------- | ---------------------------------- |
| `hashtag_id` | string | `"229207"` |
| `name` | string | `"fyp"` |
| `description` | string or null | |
| `post_count` | number | `534395710` |
| `view_count` | number | `125407420251356` |
| `cover_url` | string or 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":"booktok","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",
"hashtag_id": "1622962893630470",
"has_more": true,
"aweme_list": [
{
"aweme_id": "7663880033508887838",
"desc": "Some books go by so fast you can’t even keep up! These books were unputdownable!!! #BookTok #bookrecommendation #bookish #fyp",
"url": "https://www.tiktok.com/@brithefunnyfictionista/video/7663880033508887838",
"create_time": 1784475000,
"music": {
"author": "brithefunnyfictionista",
"id": "7663880106586147614",
"title": "original sound - brithefunnyfictionista",
"id_str": "7663880106586147614",
"mid": "7663880106586147614",
"owner_nickname": "brithefunnyfictionista",
"duration": 529,
"is_original": true,
"is_original_sound": true,
"cover_large": {
"uri": "https://p16-common-sign.tiktokcdn-us.com/tos-useast8-avt-0068-tx2/5b46b36cc3d7706bac7c5cd1d1b56851~tplv-tiktokx-cropcenter:1080:1080.jpeg",
"url_list": [
"https://p16-common-sign.tiktokcdn-us.com/tos-useast8-avt-0068-tx2/5b46b36cc3d7706bac7c5cd1d1b56851~tplv-tiktokx-cropcenter:1080:1080.jpeg"
]
},
"cover_medium": {
"uri": "https://p16-common-sign.tiktokcdn-us.com/tos-useast8-avt-0068-tx2/5b46b36cc3d7706bac7c5cd1d1b56851~tplv-tiktokx-cropcenter:1080:1080.jpeg",
"url_list": [
"https://p16-common-sign.tiktokcdn-us.com/tos-useast8-avt-0068-tx2/5b46b36cc3d7706bac7c5cd1d1b56851~tplv-tiktokx-cropcenter:1080:1080.jpeg"
]
},
"cover_thumb": {
"uri": "https://p16-common-sign.tiktokcdn-us.com/tos-useast8-avt-0068-tx2/5b46b36cc3d7706bac7c5cd1d1b56851~tplv-tiktokx-cropcenter:1080:1080.jpeg",
"url_list": [
"https://p16-common-sign.tiktokcdn-us.com/tos-useast8-avt-0068-tx2/5b46b36cc3d7706bac7c5cd1d1b56851~tplv-tiktokx-cropcenter:1080:1080.jpeg"
]
},
"play_url": {
"uri": "https://sf19.tiktokcdn-us.com/obj/ies-music-tx2/7667615441157622558.mp3",
"url_list": [
"https://sf19.tiktokcdn-us.com/obj/ies-music-tx2/7667615441157622558.mp3"
]
}
},
"video": {
"data_size": 73392163,
"duration": 529,
"watermark_data_size": 68747364,
"cover": {
"uri": "https://p16-common-sign.tiktokcdn-us.com/tos-useast8-p-0068-tx2/oMbO3AuK4VGBFEQqaWFfEBA70Jej9aQ9R6DzEA~tplv-tiktokx-origin.image",
"url_list": [
"https://p16-common-sign.tiktokcdn-us.com/tos-useast8-p-0068-tx2/oMbO3AuK4VGBFEQqaWFfEBA70Jej9aQ9R6DzEA~tplv-tiktokx-origin.image"
]
},
"download_addr": {
"uri": "https://v45.tiktokcdn-us.com/af7f1f0b95bc9741baefef44580055c4/6a76e854/video/tos/useast8/tos-useast8-ve-0068c003-tx2/ogetIJBqEAkE8BRNBE7xfRaAbA8DWFz94V3kiE/",
"url_list": [
"https://v45.tiktokcdn-us.com/af7f1f0b95bc9741baefef44580055c4/6a76e854/video/tos/useast8/tos-useast8-ve-0068c003-tx2/ogetIJBqEAkE8BRNBE7xfRaAbA8DWFz94V3kiE/"
]
},
"dynamic_cover": {
"uri": "https://p16-common-sign.tiktokcdn-us.com/tos-useast8-p-0068-tx2/o8bNzFBRVDq5WiE9kAYtAxm3IfaAe8EEFgIT4B~tplv-tiktokx-origin.image",
"url_list": [
"https://p16-common-sign.tiktokcdn-us.com/tos-useast8-p-0068-tx2/o8bNzFBRVDq5WiE9kAYtAxm3IfaAe8EEFgIT4B~tplv-tiktokx-origin.image"
]
},
"origin_cover": {
"uri": "https://p19-common-sign.tiktokcdn-us.com/tos-useast8-p-0068-tx2/oARB9FE4CbAfJzW9mqTiAaVbmfQEQTuFD4k0EA~tplv-tiktokx-shrink-aq:360:360:q75.webp",
"url_list": [
"https://p19-common-sign.tiktokcdn-us.com/tos-useast8-p-0068-tx2/oARB9FE4CbAfJzW9mqTiAaVbmfQEQTuFD4k0EA~tplv-tiktokx-shrink-aq:360:360:q75.webp"
]
},
"play_addr": {
"uri": "https://v45.tiktokcdn-us.com/d2b33593d096eb26ea2870da67bcca21/6a76e854/video/tos/useast8/tos-useast8-ve-0068c001-tx2/oM1uQaFlfbVAp0UbEiDAI9WzR9qAkBhEL4EFfP/",
"url_list": [
"https://v45.tiktokcdn-us.com/d2b33593d096eb26ea2870da67bcca21/6a76e854/video/tos/useast8/tos-useast8-ve-0068c001-tx2/oM1uQaFlfbVAp0UbEiDAI9WzR9qAkBhEL4EFfP/"
]
}
},
"author": {
"nickname": "brithefunnyfictionista",
"unique_id": "brithefunnyfictionista",
"region": "US",
"uid": "6786348082407425029",
"avatar_larger": {
"uri": "https://p16-common-sign.tiktokcdn-us.com/tos-useast8-avt-0068-tx2/5b46b36cc3d7706bac7c5cd1d1b56851~tplv-tiktokx-cropcenter:300:300.jpeg",
"url_list": [
"https://p16-common-sign.tiktokcdn-us.com/tos-useast8-avt-0068-tx2/5b46b36cc3d7706bac7c5cd1d1b56851~tplv-tiktokx-cropcenter:300:300.jpeg"
]
},
"avatar_medium": {
"uri": "https://p16-common-sign.tiktokcdn-us.com/tos-useast8-avt-0068-tx2/5b46b36cc3d7706bac7c5cd1d1b56851~tplv-tiktokx-cropcenter:300:300.jpeg",
"url_list": [
"https://p16-common-sign.tiktokcdn-us.com/tos-useast8-avt-0068-tx2/5b46b36cc3d7706bac7c5cd1d1b56851~tplv-tiktokx-cropcenter:300:300.jpeg"
]
},
"avatar_thumb": {
"uri": "https://p16-common-sign.tiktokcdn-us.com/tos-useast8-avt-0068-tx2/5b46b36cc3d7706bac7c5cd1d1b56851~tplv-tiktokx-cropcenter:300:300.jpeg",
"url_list": [
"https://p16-common-sign.tiktokcdn-us.com/tos-useast8-avt-0068-tx2/5b46b36cc3d7706bac7c5cd1d1b56851~tplv-tiktokx-cropcenter:300:300.jpeg"
]
}
},
"statistics": {
"aweme_id": "7663880033508887838",
"collect_count": 17138,
"comment_count": 630,
"play_count": 276251,
"share_count": 1944,
"digg_count": 30953,
"download_count": 302
},
"author_user_id": "6786348082407425029",
"create_time_utc": "2026-07-19T15:30:00.000Z",
"media_id": "v15044gf0000d9doug7og65pvbcbeq6g",
"region": "US",
"aweme_type": 0,
"is_ad": false,
"is_nff_or_nr": false,
"is_top": 0,
"item_comment_settings": 0,
"anchors": [
{
"id": "363379",
"component_key": "anchor_effect",
"description": "Effects",
"extra": "{\"effect_source\":0,\"is_commerce\":0,\"resource_id\":6745493419897917960}",
"keyword": "Inverted",
"log_extra": "{\"anchor_id\":\"363379\",\"anchor_name\":\"Inverted\",\"anchor_type\":\"prop\",\"has_friends_info\":\"0\"}",
"type": 28,
"actions": [
{
"schema": "shoot",
"action_type": 1,
"icon": {
"uri": "tiktok-obj/28px_primary_create_onDark3x.png",
"height": 720,
"width": 720,
"url_list": [
"https://p16-common.tiktokcdn-us.com/tiktok-obj/28px_primary_create_onDark3x.png~tplv-tiktokx-origin.image",
"https://p19-common.tiktokcdn-us.com/tiktok-obj/28px_primary_create_onDark3x.png~tplv-tiktokx-origin.image",
"https://p16-common.tiktokcdn-us.com/tiktok-obj/28px_primary_create_onDark3x.png~tplv-tiktokx-origin.jpeg"
]
}
}
],
"icon": {
"uri": "tiktok-obj/20px_anchor_effect3x.png",
"height": 720,
"width": 720,
"url_list": [
"https://p16-common.tiktokcdn-us.com/tiktok-obj/20px_anchor_effect3x.png~tplv-tiktokx-origin.image",
"https://p19-common.tiktokcdn-us.com/tiktok-obj/20px_anchor_effect3x.png~tplv-tiktokx-origin.image",
"https://p16-common.tiktokcdn-us.com/tiktok-obj/20px_anchor_effect3x.png~tplv-tiktokx-origin.jpeg"
]
},
"thumbnail": {
"uri": "0baa580af8f44f504ad6eeb2cf3d3d7d",
"height": 64,
"width": 64,
"url_list": [
"https://lf16-effectcdn-us.tiktokcdn-us.com/obj/tiktok-loki-effect-oracle-tx/0baa580af8f44f504ad6eeb2cf3d3d7d",
"https://lf19-effectcdn-us.tiktokcdn-us.com/obj/tiktok-loki-effect-oracle-tx/0baa580af8f44f504ad6eeb2cf3d3d7d"
]
}
}
],
"commerce_info": {
"adv_promotable": false,
"auction_ad_invited": false,
"branded_content_type": 0,
"is_diversion_ad": 0,
"with_comment_filter_words": false
}
}
],
"hashtag": {
"cover_url": "https://p19-common-sign.tiktokcdn.com/tiktok-obj/ffd11355ceddd5cb7a3f7f4a1f059df0.png~tplv-tiktokx-origin.image",
"description": "Calling all book lovers, join the #BookTok Post Contest from April 13th to May 11th for a chance to win $3000! Click here to join: https://vt.tiktok.com/ZSHgdjSGp/",
"hashtag_id": "1622962893630470",
"hashtag_link": "https://www.tiktok.com/tag/BookTok",
"name": "BookTok",
"is_challenge": false,
"is_commerce": false,
"is_pgc_show": false,
"is_strong_music": false,
"post_count": 83697988,
"type": 2,
"view_count": 540703741652
}
}
```
`hashtag` fields:
| Field | Type | Example |
| ----------------- | -------------- | ---------------------------------- |
| `hashtag_id` | string | `"229207"` |
| `name` | string | `"fyp"` |
| `description` | string or null | |
| `post_count` | number | `534395718` |
| `view_count` | number | `125407420827330` |
| `cover_url` | string or 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",
"keywords": "travel",
"has_more": true,
"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",
"name": "Travel",
"is_challenge": false,
"is_commerce": false,
"is_pgc_show": false,
"is_strong_music": false,
"post_count": 91212510,
"type": 2,
"view_count": 747530458231
}
]
}
```
## 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_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,
"creator_id": null,
"creator_name": null
}
}
```
`playlist` fields:
| Field | Type | Example |
| ------------------ | -------------- | ----------------------------------------- |
| `playlist_id` | string | `"7659874208872221471"` |
| `name` | string | `"Behind The Breakthrough"` |
| `type` | number | `1` |
| `video_count` | number | `3` |
| `creator_id` | string or null | |
| `creator_username` | string | `"tiktok"` |
| `creator_name` | string or 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",
"name": "Summer of Sports",
"state": 3,
"video_count": 139,
"creator_username": null
}
}
```
`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` | string or 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",
"max_cursor": "30",
"has_more": true,
"status_code": 0,
"videos": [
{
"desc": "I love womens sports #olympics #paris2024",
"id": "7398226505815362859",
"author": {
"id": "6902993835233444870",
"nickname": "Coach Jackie J",
"uniqueId": "jcubedhax"
},
"video": {
"cover": "https://p16-common-sign.tiktokcdn.com/tos-useast5-p-0068-tx/oYAEalx3giI92SurtZBb4UPH7E8qAvwRBiKEr~tplv-tiktokx-cropcenter-q:300:400:q70.webp",
"duration": 146
},
"createTime": 1722533845,
"anchors": [
{
"id": "286584",
"component_key": "anchor_effect",
"description": "Effects",
"extra": "{\"effect_source\":0,\"is_commerce\":0,\"resource_id\":6711137499550323208}",
"keyword": "Green Screen",
"log_extra": "{\"anchor_id\":\"263840\",\"anchor_name\":\"Green Screen\",\"anchor_type\":\"prop\",\"has_friends_info\":\"0\"}",
"type": 28,
"actions": [
{
"schema": "shoot",
"action_type": 1,
"icon": {
"uri": "tiktok-obj/28px_primary_create_onDark3x.png",
"height": 720,
"width": 720,
"url_list": [
"https://p19-common.tiktokcdn.com/tiktok-obj/28px_primary_create_onDark3x.png~tplv-tiktokx-origin.image",
"https://p16-common.tiktokcdn.com/tiktok-obj/28px_primary_create_onDark3x.png~tplv-tiktokx-origin.image",
"https://p19-common.tiktokcdn.com/tiktok-obj/28px_primary_create_onDark3x.png~tplv-tiktokx-origin.jpeg"
]
}
}
],
"icon": {
"uri": "tiktok-obj/20px_anchor_effect3x.png",
"height": 720,
"width": 720,
"url_list": [
"https://p16-common.tiktokcdn.com/tiktok-obj/20px_anchor_effect3x.png~tplv-tiktokx-origin.image",
"https://p19-common.tiktokcdn.com/tiktok-obj/20px_anchor_effect3x.png~tplv-tiktokx-origin.image",
"https://p16-common.tiktokcdn.com/tiktok-obj/20px_anchor_effect3x.png~tplv-tiktokx-origin.jpeg"
]
},
"thumbnail": {
"uri": "cfaa5ce4a49351ceb195197df28a788b",
"height": 64,
"width": 64,
"url_list": [
"https://lf16-effectcdn-sg.tiktokcdn.com/obj/ies.fe.effect.alisg/cfaa5ce4a49351ceb195197df28a788b",
"https://lf19-effectcdn-sg.tiktokcdn.com/obj/ies.fe.effect.alisg/cfaa5ce4a49351ceb195197df28a788b"
]
}
}
],
"stats": {
"collectCount": 2390,
"commentCount": 987,
"diggCount": 59072,
"playCount": 309199,
"shareCount": 7226
}
}
],
"status_msg": ""
}
```
### `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` | string or 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` | string or null | Echo of what you queried. |
```json theme={"system"}
{
"unique_id": "tiktok",
"has_more": false,
"collections": [
{
"collection_id": "7394627756635573022",
"name": "Summer of Sports",
"state": 3,
"video_count": 139
}
],
"cursor": null,
"user_id": null
}
```
### `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` | string or 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` | string or null | Echo of what you queried. |
```json theme={"system"}
{
"unique_id": "tiktok",
"has_more": false,
"playlists": [
{
"creator_username": "tiktok",
"name": "Behind The Breakthrough",
"playlist_id": "7659874208872221471",
"playlist_link": "https://www.tiktok.com/@tiktok/playlist/behind-the-breakthrough-7659874208872221471",
"type": 1
}
],
"cursor": null,
"user_id": 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",
"keywords": "cooking",
"has_more": true,
"search_item_list": [
{
"aweme_id": "7446130387908054302",
"desc": "when its your turn to make mac & cheese but you ran out of time #food #Recipe #dinner #yum #yunmy #chef #cooking #pasta #noodles #cheese #Foodie",
"url": "https://www.tiktok.com/@katewilltryanything/video/7446130387908054302",
"create_time": 1733687344,
"music": {
"author": "TLC",
"id": "7242456560241526785",
"title": "Creep (Yes it's me again)",
"album": "Creep",
"id_str": "7242456560241526785",
"mid": "7242456560241526785",
"owner_nickname": "TLC",
"duration": 60,
"is_original": false,
"is_original_sound": false,
"cover_large": {
"uri": "https://p16-common.tiktokcdn-us.com/tos-alisg-v-2774/39492910a3c44167879cadbca9d3da2a~tplv-tiktokx-cropcenter:720:720.jpeg",
"url_list": [
"https://p16-common.tiktokcdn-us.com/tos-alisg-v-2774/39492910a3c44167879cadbca9d3da2a~tplv-tiktokx-cropcenter:720:720.jpeg"
]
},
"cover_medium": {
"uri": "https://p16-common.tiktokcdn-us.com/tos-alisg-v-2774/39492910a3c44167879cadbca9d3da2a~tplv-tiktokx-cropcenter:720:720.jpeg",
"url_list": [
"https://p16-common.tiktokcdn-us.com/tos-alisg-v-2774/39492910a3c44167879cadbca9d3da2a~tplv-tiktokx-cropcenter:720:720.jpeg"
]
},
"cover_thumb": {
"uri": "https://p16-common.tiktokcdn-us.com/tos-alisg-v-2774/39492910a3c44167879cadbca9d3da2a~tplv-tiktokx-cropcenter:720:720.jpeg",
"url_list": [
"https://p16-common.tiktokcdn-us.com/tos-alisg-v-2774/39492910a3c44167879cadbca9d3da2a~tplv-tiktokx-cropcenter:720:720.jpeg"
]
},
"play_url": {
"uri": "https://v45.tiktokcdn-us.com/11629525011c5c20701abeadf8001fe1/6a7fcf77/video/tos/alisg/tos-alisg-ve-2774/oAICMHB2ZYfgCMnkCeuQbUUXKNctQDggQ5m1Bq/",
"url_list": [
"https://v45.tiktokcdn-us.com/11629525011c5c20701abeadf8001fe1/6a7fcf77/video/tos/alisg/tos-alisg-ve-2774/oAICMHB2ZYfgCMnkCeuQbUUXKNctQDggQ5m1Bq/"
]
}
},
"video": {
"data_size": 16276203,
"duration": 62,
"watermark_data_size": 15707166,
"cover": {
"uri": "https://p16-common-sign.tiktokcdn-us.com/tos-useast8-p-0068-tx2/okdKUartrFeQfAWGGQ7gQFeOfVRHAG8KNA8MQU~tplv-tiktokx-origin.image",
"url_list": [
"https://p16-common-sign.tiktokcdn-us.com/tos-useast8-p-0068-tx2/okdKUartrFeQfAWGGQ7gQFeOfVRHAG8KNA8MQU~tplv-tiktokx-origin.image"
]
},
"download_addr": {
"uri": "https://v45.tiktokcdn-us.com/31b07167722f751af4b3130306443e8e/6a76e687/video/tos/useast8/tos-useast8-ve-0068c001-tx2/ocfrrWAI9oGDgIEQxFLdAeaGAKUmdQmFefVR9D/",
"url_list": [
"https://v45.tiktokcdn-us.com/31b07167722f751af4b3130306443e8e/6a76e687/video/tos/useast8/tos-useast8-ve-0068c001-tx2/ocfrrWAI9oGDgIEQxFLdAeaGAKUmdQmFefVR9D/"
]
},
"dynamic_cover": {
"uri": "https://p19-common-sign.tiktokcdn-us.com/tos-useast8-p-0068-tx2/oERD3rQAUEALKIfeSIGfDVeoSAGsQFAQ9DDdWr~tplv-tiktokx-origin.image",
"url_list": [
"https://p19-common-sign.tiktokcdn-us.com/tos-useast8-p-0068-tx2/oERD3rQAUEALKIfeSIGfDVeoSAGsQFAQ9DDdWr~tplv-tiktokx-origin.image"
]
},
"origin_cover": {
"uri": "https://p19-common-sign.tiktokcdn-us.com/tos-useast8-p-0068-tx2/oAWdLzADOAQDDG8hAQLKVeUGreof9DfIQRFirQ~tplv-tiktokx-shrink-aq:360:360:q75.webp",
"url_list": [
"https://p19-common-sign.tiktokcdn-us.com/tos-useast8-p-0068-tx2/oAWdLzADOAQDDG8hAQLKVeUGreof9DfIQRFirQ~tplv-tiktokx-shrink-aq:360:360:q75.webp"
]
},
"play_addr": {
"uri": "https://v45.tiktokcdn-us.com/3b3ea047b93e9b1a9c09724d8d5b6a1d/6a76e687/video/tos/useast8/tos-useast8-ve-0068c003-tx2/o4rUGWFGUMdyVHRAeAfQA6F7g8ertPQQvgRCfA/",
"url_list": [
"https://v45.tiktokcdn-us.com/3b3ea047b93e9b1a9c09724d8d5b6a1d/6a76e687/video/tos/useast8/tos-useast8-ve-0068c003-tx2/o4rUGWFGUMdyVHRAeAfQA6F7g8ertPQQvgRCfA/"
]
}
},
"author": {
"nickname": "Katewilltryanything",
"unique_id": "katewilltryanything",
"region": "US",
"uid": "6806062989101024261",
"avatar_larger": {
"uri": "https://p19-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/17d07dd2f2d919f61fb989257adc78a8~tplv-tiktokx-cropcenter-q:300:300:q70.jpeg",
"url_list": [
"https://p19-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/17d07dd2f2d919f61fb989257adc78a8~tplv-tiktokx-cropcenter-q:300:300:q70.jpeg"
]
},
"avatar_medium": {
"uri": "https://p19-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/17d07dd2f2d919f61fb989257adc78a8~tplv-tiktokx-cropcenter-q:300:300:q70.jpeg",
"url_list": [
"https://p19-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/17d07dd2f2d919f61fb989257adc78a8~tplv-tiktokx-cropcenter-q:300:300:q70.jpeg"
]
},
"avatar_thumb": {
"uri": "https://p19-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/17d07dd2f2d919f61fb989257adc78a8~tplv-tiktokx-cropcenter-q:300:300:q70.jpeg",
"url_list": [
"https://p19-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/17d07dd2f2d919f61fb989257adc78a8~tplv-tiktokx-cropcenter-q:300:300:q70.jpeg"
]
}
},
"statistics": {
"aweme_id": "7446130387908054302",
"collect_count": 17126,
"comment_count": 9867,
"play_count": 7121420,
"share_count": 51799,
"digg_count": 247506,
"download_count": 1299
},
"author_user_id": "6806062989101024261",
"create_time_utc": "2024-12-08T19:49:04.000Z",
"media_id": "v15044gf0000ctavg5fog65gqqg3uvig",
"region": "US",
"aweme_type": 0,
"is_ad": false,
"is_nff_or_nr": false,
"is_top": 0,
"item_comment_settings": 0,
"commerce_info": {
"adv_promotable": false,
"auction_ad_invited": false,
"branded_content_type": 0,
"is_diversion_ad": 0,
"with_comment_filter_words": false
}
}
]
}
```
### `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",
"keywords": "cooking",
"has_more": true,
"search_item_list": [
{
"aweme_id": "7453164796880506143",
"desc": "BEST OF 2024 begins with my Loaded Hashbrowns. MILLIONS of you loved this series! It was the first time I started a \"viral recipe trend\" & Content Creators all over the internet were recreating my hashbrown recipes. It inspired me to get more creative/innovative with the recip…",
"url": "https://www.tiktok.com/@shewillevolve/video/7453164796880506143",
"create_time": 1735325174,
"music": {
"author": "🧍🏾♀️🧍🏾♀️",
"id": "7316247872453004074",
"title": "original sound - spamminandchillin",
"id_str": "7316247872453004074",
"mid": "7316247872453004074",
"owner_nickname": "🧍🏾♀️🧍🏾♀️",
"duration": 60,
"is_original": true,
"is_original_sound": true,
"cover_large": {
"uri": "https://p19-common-sign.tiktokcdn-us.com/tos-useast8-avt-0068-tx2/267e05793397405d7d0b19e503ebbca4~tplv-tiktokx-cropcenter-q:1080:1080:q70.jpeg",
"url_list": [
"https://p19-common-sign.tiktokcdn-us.com/tos-useast8-avt-0068-tx2/267e05793397405d7d0b19e503ebbca4~tplv-tiktokx-cropcenter-q:1080:1080:q70.jpeg"
]
},
"cover_medium": {
"uri": "https://p19-common-sign.tiktokcdn-us.com/tos-useast8-avt-0068-tx2/267e05793397405d7d0b19e503ebbca4~tplv-tiktokx-cropcenter-q:1080:1080:q70.jpeg",
"url_list": [
"https://p19-common-sign.tiktokcdn-us.com/tos-useast8-avt-0068-tx2/267e05793397405d7d0b19e503ebbca4~tplv-tiktokx-cropcenter-q:1080:1080:q70.jpeg"
]
},
"cover_thumb": {
"uri": "https://p19-common-sign.tiktokcdn-us.com/tos-useast8-avt-0068-tx2/267e05793397405d7d0b19e503ebbca4~tplv-tiktokx-cropcenter-q:1080:1080:q70.jpeg",
"url_list": [
"https://p19-common-sign.tiktokcdn-us.com/tos-useast8-avt-0068-tx2/267e05793397405d7d0b19e503ebbca4~tplv-tiktokx-cropcenter-q:1080:1080:q70.jpeg"
]
},
"play_url": {
"uri": "https://v19-perf.tiktokcdn-us.com/e815b1136eede1faee495de8e7f1aa86/6a7fcce1/video/tos/useast5/tos-useast5-v-27dcd7-tx/oICxpIXMBJmREAjMwifABDOZoizozyBKx5WElN/",
"url_list": [
"https://v19-perf.tiktokcdn-us.com/e815b1136eede1faee495de8e7f1aa86/6a7fcce1/video/tos/useast5/tos-useast5-v-27dcd7-tx/oICxpIXMBJmREAjMwifABDOZoizozyBKx5WElN/"
]
}
},
"author": {
"nickname": "Sheila Williams",
"unique_id": "shewillevolve",
"region": "US",
"uid": "6804225371904361478",
"avatar_larger": {
"uri": "https://p16-common-sign.tiktokcdn-us.com/tos-useast8-avt-0068-tx2/a59bfd955a4e1c5e5ece3d49b24b74fe~tplv-tiktokx-cropcenter-q:300:300:q70.jpeg",
"url_list": [
"https://p16-common-sign.tiktokcdn-us.com/tos-useast8-avt-0068-tx2/a59bfd955a4e1c5e5ece3d49b24b74fe~tplv-tiktokx-cropcenter-q:300:300:q70.jpeg"
]
},
"avatar_medium": {
"uri": "https://p16-common-sign.tiktokcdn-us.com/tos-useast8-avt-0068-tx2/a59bfd955a4e1c5e5ece3d49b24b74fe~tplv-tiktokx-cropcenter-q:300:300:q70.jpeg",
"url_list": [
"https://p16-common-sign.tiktokcdn-us.com/tos-useast8-avt-0068-tx2/a59bfd955a4e1c5e5ece3d49b24b74fe~tplv-tiktokx-cropcenter-q:300:300:q70.jpeg"
]
},
"avatar_thumb": {
"uri": "https://p16-common-sign.tiktokcdn-us.com/tos-useast8-avt-0068-tx2/a59bfd955a4e1c5e5ece3d49b24b74fe~tplv-tiktokx-cropcenter-q:300:300:q70.jpeg",
"url_list": [
"https://p16-common-sign.tiktokcdn-us.com/tos-useast8-avt-0068-tx2/a59bfd955a4e1c5e5ece3d49b24b74fe~tplv-tiktokx-cropcenter-q:300:300:q70.jpeg"
]
}
},
"video": {
"duration": 13,
"cover": {
"uri": "https://p16-common-sign.tiktokcdn-us.com/tos-useast8-p-0068-tx2/o4CHAFZbvFBAzExAEnEDfbf9IA2yAWNLEVv9lR~tplv-tiktokx-origin.image",
"url_list": [
"https://p16-common-sign.tiktokcdn-us.com/tos-useast8-p-0068-tx2/o4CHAFZbvFBAzExAEnEDfbf9IA2yAWNLEVv9lR~tplv-tiktokx-origin.image"
]
},
"download_addr": {
"uri": "https://v16m-perf.tiktokcdn-us.com/549ef2aa0097d1db2565b3ac7ebf938f/6a76e656/video/tos/useast8/tos-useast8-ve-0068c003-tx2/okuDOFAgiR1t7wy2BAEzZQ9iIQhBgUT2vVEHE/",
"url_list": [
"https://v16m-perf.tiktokcdn-us.com/549ef2aa0097d1db2565b3ac7ebf938f/6a76e656/video/tos/useast8/tos-useast8-ve-0068c003-tx2/okuDOFAgiR1t7wy2BAEzZQ9iIQhBgUT2vVEHE/"
]
},
"dynamic_cover": {
"uri": "https://p16-common-sign.tiktokcdn-us.com/tos-useast8-p-0068-tx2/o4CHAFZbvFBAzExAEnEDfbf9IA2yAWNLEVv9lR~tplv-tiktokx-origin.image",
"url_list": [
"https://p16-common-sign.tiktokcdn-us.com/tos-useast8-p-0068-tx2/o4CHAFZbvFBAzExAEnEDfbf9IA2yAWNLEVv9lR~tplv-tiktokx-origin.image"
]
},
"origin_cover": {
"uri": "https://p16-common-sign.tiktokcdn-us.com/tos-useast8-p-0068-tx2/o81t6vhnDQjfcdkUAAFEVURWgBfnnYEQEQAhEb~tplv-tiktokx-shrink-aq:360:360:q75.jpeg",
"url_list": [
"https://p16-common-sign.tiktokcdn-us.com/tos-useast8-p-0068-tx2/o81t6vhnDQjfcdkUAAFEVURWgBfnnYEQEQAhEb~tplv-tiktokx-shrink-aq:360:360:q75.jpeg"
]
},
"play_addr": {
"uri": "https://v16m-perf.tiktokcdn-us.com/9c1d4b45777f6f5fd9c0beefdebac880/6a76e656/video/tos/useast8/tos-useast8-ve-0068c004-tx2/okAgdFAWUbnfD6CGRfhBv2EkAVEOELIIgnQtQc/",
"url_list": [
"https://v16m-perf.tiktokcdn-us.com/9c1d4b45777f6f5fd9c0beefdebac880/6a76e656/video/tos/useast8/tos-useast8-ve-0068c004-tx2/okAgdFAWUbnfD6CGRfhBv2EkAVEOELIIgnQtQc/"
]
}
},
"statistics": {
"aweme_id": "7453164796880506143",
"comment_count": 1113,
"play_count": 6592938,
"share_count": 94047,
"digg_count": 381956,
"download_count": 7129
},
"author_user_id": "6804225371904361478",
"create_time_utc": "2024-12-27T18:46:14.000Z",
"media_id": "v15044gf0000ctnfa5nog65i9s6q0g70",
"region": "US",
"aweme_type": 0,
"is_ad": false,
"is_nff_or_nr": false,
"is_top": 0,
"item_comment_settings": 0,
"anchors": [
{
"id": "7453164750583742506",
"component_key": "anchor_ucg_template",
"description": "Templates",
"extra": "{\"tags\":\"\",\"music_post_unavailable\":\"false\",\"title\":\"\",\"sub_type\":\"ugc\",\"dispatch_type\":\"ugc_create\",\"nle_summary\":\"{\\\"slots\\\":\\\"[{\\\\\\\"clip_end\\\\\\\":4.102272033691406,\\\\\\\"clip_start\\\\\\\":0.0,\\\\\\\"description\\\\\\\":\\\\\\\"\\\\\\\",\\\\\\\"endtime\\\\\\\":4.102272033691406,\\\\\\\"height\\\\\\\":1920,\\\\\\\"o…",
"keyword": "Try TikTok template",
"log_extra": "{\"anchor_id\":\"7453164750583742506\",\"anchor_name\":\"Try TikTok template\",\"anchor_type\":\"ugc_template\",\"has_friends_info\":\"0\"}",
"type": 65,
"actions": [
{
"schema": "shoot",
"action_type": 1,
"icon": {
"uri": "tiktok-obj/28px_primary_create_onDark3x.png",
"height": 720,
"width": 720,
"url_list": [
"https://p16-common.tiktokcdn-us.com/tiktok-obj/28px_primary_create_onDark3x.png~tplv-tiktokx-origin.image",
"https://p19-common.tiktokcdn-us.com/tiktok-obj/28px_primary_create_onDark3x.png~tplv-tiktokx-origin.image",
"https://p16-common.tiktokcdn-us.com/tiktok-obj/28px_primary_create_onDark3x.png~tplv-tiktokx-origin.jpeg"
]
}
}
],
"icon": {
"uri": "tiktok-obj/Templates_Cards.png",
"height": 720,
"width": 720,
"url_list": [
"https://p16-common.tiktokcdn-us.com/tiktok-obj/Templates_Cards.png~tplv-tiktokx-origin.image",
"https://p19-common.tiktokcdn-us.com/tiktok-obj/Templates_Cards.png~tplv-tiktokx-origin.image",
"https://p16-common.tiktokcdn-us.com/tiktok-obj/Templates_Cards.png~tplv-tiktokx-origin.jpeg"
]
},
"thumbnail": {
"uri": "tiktok-obj/Templates_Cards.png",
"height": 720,
"width": 720,
"url_list": [
"https://p16-common.tiktokcdn-us.com/tiktok-obj/Templates_Cards.png~tplv-tiktokx-origin.image",
"https://p19-common.tiktokcdn-us.com/tiktok-obj/Templates_Cards.png~tplv-tiktokx-origin.image",
"https://p16-common.tiktokcdn-us.com/tiktok-obj/Templates_Cards.png~tplv-tiktokx-origin.jpeg"
]
}
}
],
"commerce_info": {
"adv_promotable": false,
"auction_ad_invited": false,
"branded_content_type": 0,
"is_diversion_ad": 0,
"with_comment_filter_words": false
}
}
]
}
```
### `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",
"keywords": "cooking",
"has_more": true,
"users": [
{
"nickname": "cookming_",
"unique_id": "cookming_",
"region": "TW",
"sec_uid": "MS4wLjABAAAAlZhACVHYe5dPsS1NUAwnpBpZc0Z3wuyZak06MYc7hI32RDZBZO1lqqJITpY9wrW3",
"signature": "have a nice day : )✨\n🇨🇦\n📧 [email redacted]\n🚫 My videos are NOT available for reuse.",
"uid": "7509165839188624389",
"aweme_count": 250,
"favoriting_count": 167,
"follower_count": 1445751,
"following_count": 2,
"total_favorited": 87979942,
"verified": false,
"avatar_larger": {
"uri": "https://p16-common-sign.tiktokcdn-us.com/tos-maliva-avt-0068/8095f6f247baa93026e3f977437af172~tplv-tiktokx-cropcenter-q:1080:1080:q70.webp",
"url_list": [
"https://p16-common-sign.tiktokcdn-us.com/tos-maliva-avt-0068/8095f6f247baa93026e3f977437af172~tplv-tiktokx-cropcenter-q:1080:1080:q70.webp"
]
},
"avatar_medium": {
"uri": "https://p16-common-sign.tiktokcdn-us.com/tos-maliva-avt-0068/8095f6f247baa93026e3f977437af172~tplv-tiktokx-cropcenter-q:720:720:q70.webp",
"url_list": [
"https://p16-common-sign.tiktokcdn-us.com/tos-maliva-avt-0068/8095f6f247baa93026e3f977437af172~tplv-tiktokx-cropcenter-q:720:720:q70.webp"
]
},
"avatar_thumb": {
"uri": "https://p16-common-sign.tiktokcdn-us.com/tos-maliva-avt-0068/8095f6f247baa93026e3f977437af172~tplv-tiktokx-cropcenter-q:100:100:q70.webp",
"url_list": [
"https://p16-common-sign.tiktokcdn-us.com/tos-maliva-avt-0068/8095f6f247baa93026e3f977437af172~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",
"query": "cooking",
"has_more": true,
"publish_time": 0,
"sort_type": 0,
"items": [
{
"create_time": "2021-12-03T22:17:01.000Z",
"desc": "Creamy crunchy bubble potato pillows #cooking #foodasmr #asmrcooking #vegan #Recipe #homecook #potato #foodtiktok #veganrecipes",
"id": "7037603785962933550",
"url": "https://www.tiktok.com/@msshiandmrhe/video/7037603785962933550",
"music": {
"author": "Frank Sinatra",
"id": "6715995005141387266",
"title": "Let It Snow! Let It Snow!",
"album": "A Sinatra Christmas",
"id_str": "6715995005141387266",
"mid": "6715995005141387266",
"owner_nickname": "Frank Sinatra",
"duration": 60,
"is_original": false,
"is_original_sound": false,
"cover_large": {
"uri": "https://p19-common-sign.tiktokcdn-us.com/tos-alisg-v-2774/cb2a84c9acc541bd9883a37c3f6a1964~tplv-tiktokx-cropcenter:720:720.jpeg",
"url_list": [
"https://p19-common-sign.tiktokcdn-us.com/tos-alisg-v-2774/cb2a84c9acc541bd9883a37c3f6a1964~tplv-tiktokx-cropcenter:720:720.jpeg"
]
},
"cover_medium": {
"uri": "https://p19-common-sign.tiktokcdn-us.com/tos-alisg-v-2774/cb2a84c9acc541bd9883a37c3f6a1964~tplv-tiktokx-cropcenter:720:720.jpeg",
"url_list": [
"https://p19-common-sign.tiktokcdn-us.com/tos-alisg-v-2774/cb2a84c9acc541bd9883a37c3f6a1964~tplv-tiktokx-cropcenter:720:720.jpeg"
]
},
"cover_thumb": {
"uri": "https://p19-common-sign.tiktokcdn-us.com/tos-alisg-v-2774/cb2a84c9acc541bd9883a37c3f6a1964~tplv-tiktokx-cropcenter:720:720.jpeg",
"url_list": [
"https://p19-common-sign.tiktokcdn-us.com/tos-alisg-v-2774/cb2a84c9acc541bd9883a37c3f6a1964~tplv-tiktokx-cropcenter:720:720.jpeg"
]
},
"play_url": {
"uri": "https://sf16-sign.tiktokcdn-us.com/obj/tos-alisg-ve-2774/o0bya13tZMZC5QrfykIOpXBom49iiBLfBgnP5G",
"url_list": [
"https://sf16-sign.tiktokcdn-us.com/obj/tos-alisg-ve-2774/o0bya13tZMZC5QrfykIOpXBom49iiBLfBgnP5G"
]
}
},
"video": {
"data_size": 11522669,
"duration": 44,
"watermark_data_size": 11461833,
"cover": {
"uri": "https://p19-common-sign.tiktokcdn-us.com/tos-useast5-p-0068-tx/66f6d6a70fd94123a01182b8f0d0ed03_1638569828~tplv-tiktokx-cropcenter:500:800.jpeg",
"url_list": [
"https://p19-common-sign.tiktokcdn-us.com/tos-useast5-p-0068-tx/66f6d6a70fd94123a01182b8f0d0ed03_1638569828~tplv-tiktokx-cropcenter:500:800.jpeg"
]
},
"download_addr": {
"uri": "https://v45.tiktokcdn-us.com/9b519fa29bd2bf5d01efa7cfa16e7c09/6a76e678/video/tos/useast5/tos-useast5-ve-0068c004-tx/614e9b7e095b487da2ec7a89ad1f4cc2/",
"url_list": [
"https://v45.tiktokcdn-us.com/9b519fa29bd2bf5d01efa7cfa16e7c09/6a76e678/video/tos/useast5/tos-useast5-ve-0068c004-tx/614e9b7e095b487da2ec7a89ad1f4cc2/"
]
},
"dynamic_cover": {
"uri": "https://p16-common-sign.tiktokcdn-us.com/tos-useast5-p-0068-tx/4222352a23f8458d821a35eef85453aa_1638569822~tplv-tiktokx-dmt-logom:tos-useast5-p-0000-tx/80fa294c724041958cb3697cc80d82d0.image",
"url_list": [
"https://p16-common-sign.tiktokcdn-us.com/tos-useast5-p-0068-tx/4222352a23f8458d821a35eef85453aa_1638569822~tplv-tiktokx-dmt-logom:tos-useast5-p-0000-tx/80fa294c724041958cb3697cc80d82d0.image"
]
},
"origin_cover": {
"uri": "https://p19-common-sign.tiktokcdn-us.com/tos-useast5-p-0068-tx/4d9e75d5cffd46a6bd5c2894ae3ca38c_1638569822~tplv-tiktokx-shrink-aq:360:360:q75.webp",
"url_list": [
"https://p19-common-sign.tiktokcdn-us.com/tos-useast5-p-0068-tx/4d9e75d5cffd46a6bd5c2894ae3ca38c_1638569822~tplv-tiktokx-shrink-aq:360:360:q75.webp"
]
},
"play_addr": {
"uri": "https://v45.tiktokcdn-us.com/a7aeb6b517fc4c428f508619cb9f63ec/6a76e678/video/tos/useast5/tos-useast5-pve-0068-tx/fe2019632005495c9443d89293d76f98/",
"url_list": [
"https://v45.tiktokcdn-us.com/a7aeb6b517fc4c428f508619cb9f63ec/6a76e678/video/tos/useast5/tos-useast5-pve-0068-tx/fe2019632005495c9443d89293d76f98/"
]
}
},
"author": {
"nickname": "Ms Shi & Mr He",
"unique_id": "msshiandmrhe",
"region": "US",
"uid": "6790833782485615622",
"avatar_larger": {
"uri": "https://p19-common-sign.tiktokcdn-us.com/tos-maliva-avt-0068/ee39ac6ae8584d51bf545a74cd73794c~tplv-tiktokx-cropcenter-q:300:300:q70.jpeg",
"url_list": [
"https://p19-common-sign.tiktokcdn-us.com/tos-maliva-avt-0068/ee39ac6ae8584d51bf545a74cd73794c~tplv-tiktokx-cropcenter-q:300:300:q70.jpeg"
]
},
"avatar_medium": {
"uri": "https://p19-common-sign.tiktokcdn-us.com/tos-maliva-avt-0068/ee39ac6ae8584d51bf545a74cd73794c~tplv-tiktokx-cropcenter-q:300:300:q70.jpeg",
"url_list": [
"https://p19-common-sign.tiktokcdn-us.com/tos-maliva-avt-0068/ee39ac6ae8584d51bf545a74cd73794c~tplv-tiktokx-cropcenter-q:300:300:q70.jpeg"
]
},
"avatar_thumb": {
"uri": "https://p19-common-sign.tiktokcdn-us.com/tos-maliva-avt-0068/ee39ac6ae8584d51bf545a74cd73794c~tplv-tiktokx-cropcenter-q:300:300:q70.jpeg",
"url_list": [
"https://p19-common-sign.tiktokcdn-us.com/tos-maliva-avt-0068/ee39ac6ae8584d51bf545a74cd73794c~tplv-tiktokx-cropcenter-q:300:300:q70.jpeg"
]
}
},
"statistics": {
"aweme_id": "7037603785962933550",
"collect_count": 1861177,
"comment_count": 39478,
"play_count": 113908946,
"share_count": 467449,
"digg_count": 10794331,
"download_count": 818326
},
"content_type": "video",
"region": "US",
"is_ad": false,
"is_top": 0
}
],
"users": [
{
"username": "cookingwithlynja",
"avatar_medium": "https://p16-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/7310587793867014186~tplv-tiktokx-cropcenter-q:720:720:q70.webp",
"avatar_thumb": "https://p16-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👇",
"display_name": "Lynja",
"instagram_id": "cookingwithlynja",
"privacy_status": "public",
"profile_id": "6834290048143049733",
"profile_image": "https://p16-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",
"youtube_channel_id": "UCjvGPQTRr2eIEhthL5y31VQ",
"youtube_channel_title": "Cooking With Lynja",
"content_count": 507,
"follower_count": 22235015,
"following_count": 61,
"is_ad_virtual": false,
"is_under_18": false,
"total_likes": 361119475,
"total_reactions": 361119475,
"verification_status": true
}
],
"hashtags": [
{
"cover_url": "https://p16-amd-va.tiktokcdn.com/obj/musically-maliva-obj/36154a31cfad9d1b9e317efd24c99b21",
"description": "Find a recipe, grab your ingredients, and show us your #CookingTips.",
"hashtag_id": "8620710",
"hashtag_link": "https://www.tiktok.com/tag/cookingtips",
"name": "cookingtips",
"is_challenge": false,
"is_commerce": false,
"is_pgc_show": false,
"is_strong_music": false,
"post_count": 590088,
"type": 2,
"view_count": 11772198646
}
]
}
```
### `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` | string or null | Echo of what you queried. |
```json theme={"system"}
{
"query": "coff",
"suggestions": [
{
"language": "en",
"text": "coffee",
"group_id": "4928213053111302118",
"position": 0,
"score": 0.027565962
}
],
"region": null
}
```
### `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` | string or null | Pass back on the next call. `null` once the list is exhausted. |
| `has_more` | boolean | Whether another page exists. |
```json theme={"system"}
{
"region": "US",
"has_more": false,
"aweme_list": [
{
"aweme_id": "7666535586920140052",
"desc": "📸 style inspiration 👗vibe check 💸 layering techniques 📝 personal style tips ##\"authoritative guy outfit\" for ngatasin _ bad day - yes? *** Let it still look firm + confident even though again - bad mood _, the key: simple, neat, and neutral color. Authoritative outfit …",
"url": "https://www.tiktok.com/@hwi9662/photo/7666535586920140052",
"create_time": 1785004423,
"music": {
"author": "Ebbaa19",
"id": "7504321566572186374",
"title": "original sound - ebbaa19",
"id_str": "7504321566572186374",
"mid": "7504321566572186374",
"owner_nickname": "Ebbaa19",
"duration": 72,
"is_original": false,
"is_original_sound": false,
"cover_large": {
"uri": "https://p19-common-sign.tiktokcdn.com/tos-maliva-avt-0068/3f5d607f9aeec9f5cc67b9027f7741ed~tplv-tiktokx-cropcenter-q:1080:1080:q70.webp",
"url_list": [
"https://p19-common-sign.tiktokcdn.com/tos-maliva-avt-0068/3f5d607f9aeec9f5cc67b9027f7741ed~tplv-tiktokx-cropcenter-q:1080:1080:q70.webp"
]
},
"cover_medium": {
"uri": "https://p19-common-sign.tiktokcdn.com/tos-maliva-avt-0068/3f5d607f9aeec9f5cc67b9027f7741ed~tplv-tiktokx-cropcenter-q:1080:1080:q70.webp",
"url_list": [
"https://p19-common-sign.tiktokcdn.com/tos-maliva-avt-0068/3f5d607f9aeec9f5cc67b9027f7741ed~tplv-tiktokx-cropcenter-q:1080:1080:q70.webp"
]
},
"cover_thumb": {
"uri": "https://p19-common-sign.tiktokcdn.com/tos-maliva-avt-0068/3f5d607f9aeec9f5cc67b9027f7741ed~tplv-tiktokx-cropcenter-q:1080:1080:q70.webp",
"url_list": [
"https://p19-common-sign.tiktokcdn.com/tos-maliva-avt-0068/3f5d607f9aeec9f5cc67b9027f7741ed~tplv-tiktokx-cropcenter-q:1080:1080:q70.webp"
]
},
"play_url": {
"uri": "https://sf16-ies-music-va.tiktokcdn.com/obj/musically-maliva-obj/7504321593289231109.mp3",
"url_list": [
"https://sf16-ies-music-va.tiktokcdn.com/obj/musically-maliva-obj/7504321593289231109.mp3"
]
}
},
"video": {
"data_size": 0,
"duration": 0,
"watermark_data_size": 0,
"cover": {
"uri": "https://p16-common-sign.tiktokcdn.com/tos-alisg-i-photomode-sg/ecb7ae8ccd07403090fb7ebedd91191e~tplv-photomode-image-cover:640:0:q70.webp",
"url_list": [
"https://p16-common-sign.tiktokcdn.com/tos-alisg-i-photomode-sg/ecb7ae8ccd07403090fb7ebedd91191e~tplv-photomode-image-cover:640:0:q70.webp"
]
},
"download_addr": {
"uri": "https://sf16-ies-music-va.tiktokcdn.com/obj/musically-maliva-obj/7504321593289231109.mp3",
"url_list": [
"https://sf16-ies-music-va.tiktokcdn.com/obj/musically-maliva-obj/7504321593289231109.mp3"
]
},
"dynamic_cover": {
"uri": "https://p16-common-sign.tiktokcdn.com/tos-alisg-i-photomode-sg/ecb7ae8ccd07403090fb7ebedd91191e~tplv-photomode-image-cover:640:0:q70.webp",
"url_list": [
"https://p16-common-sign.tiktokcdn.com/tos-alisg-i-photomode-sg/ecb7ae8ccd07403090fb7ebedd91191e~tplv-photomode-image-cover:640:0:q70.webp"
]
},
"origin_cover": {
"uri": "https://p16-common-sign.tiktokcdn.com/tos-alisg-i-photomode-sg/ecb7ae8ccd07403090fb7ebedd91191e~tplv-photomode-image-cover:640:0:q70.webp",
"url_list": [
"https://p16-common-sign.tiktokcdn.com/tos-alisg-i-photomode-sg/ecb7ae8ccd07403090fb7ebedd91191e~tplv-photomode-image-cover:640:0:q70.webp"
]
},
"play_addr": {
"uri": "https://sf16-ies-music-va.tiktokcdn.com/obj/musically-maliva-obj/7504321593289231109.mp3",
"url_list": [
"https://sf16-ies-music-va.tiktokcdn.com/obj/musically-maliva-obj/7504321593289231109.mp3"
]
}
},
"image_post_info": {
"images": [
{
"display_image": {
"uri": "https://p19-common-sign.tiktokcdn.com/tos-alisg-i-photomode-sg/ecb7ae8ccd07403090fb7ebedd91191e~tplv-photomode-sr-vqe4:1440:0:1080:0:q75.webp",
"url_list": [
"https://p19-common-sign.tiktokcdn.com/tos-alisg-i-photomode-sg/ecb7ae8ccd07403090fb7ebedd91191e~tplv-photomode-sr-vqe4:1440:0:1080:0:q75.webp"
]
},
"owner_watermark_image": {
"uri": "https://p19-common-sign.tiktokcdn.com/tos-alisg-i-photomode-sg/ecb7ae8ccd07403090fb7ebedd91191e~tplv-photomode-sr-vqe4:1440:0:1080:0:q75.webp",
"url_list": [
"https://p19-common-sign.tiktokcdn.com/tos-alisg-i-photomode-sg/ecb7ae8ccd07403090fb7ebedd91191e~tplv-photomode-sr-vqe4:1440:0:1080:0:q75.webp"
]
}
}
],
"image_post_cover": {
"display_image": {
"uri": "https://p19-common-sign.tiktokcdn.com/tos-alisg-i-photomode-sg/ecb7ae8ccd07403090fb7ebedd91191e~tplv-photomode-sr-vqe4:1440:0:1080:0:q75.webp",
"url_list": [
"https://p19-common-sign.tiktokcdn.com/tos-alisg-i-photomode-sg/ecb7ae8ccd07403090fb7ebedd91191e~tplv-photomode-sr-vqe4:1440:0:1080:0:q75.webp"
]
},
"owner_watermark_image": {
"uri": "https://p19-common-sign.tiktokcdn.com/tos-alisg-i-photomode-sg/ecb7ae8ccd07403090fb7ebedd91191e~tplv-photomode-sr-vqe4:1440:0:1080:0:q75.webp",
"url_list": [
"https://p19-common-sign.tiktokcdn.com/tos-alisg-i-photomode-sg/ecb7ae8ccd07403090fb7ebedd91191e~tplv-photomode-sr-vqe4:1440:0:1080:0:q75.webp"
]
}
}
},
"author": {
"nickname": "Hãwi Øř☦️💎🦋",
"unique_id": "hwi9662",
"region": "SA",
"uid": "7381072754353325063",
"avatar_larger": {
"uri": "https://p19-common-sign.tiktokcdn.com/tos-alisg-avt-0068/51a2e0497780c6b5846176667b2d3cba~tplv-tiktokx-cropcenter-q:300:300:q70.webp",
"url_list": [
"https://p19-common-sign.tiktokcdn.com/tos-alisg-avt-0068/51a2e0497780c6b5846176667b2d3cba~tplv-tiktokx-cropcenter-q:300:300:q70.webp"
]
},
"avatar_medium": {
"uri": "https://p19-common-sign.tiktokcdn.com/tos-alisg-avt-0068/51a2e0497780c6b5846176667b2d3cba~tplv-tiktokx-cropcenter-q:300:300:q70.webp",
"url_list": [
"https://p19-common-sign.tiktokcdn.com/tos-alisg-avt-0068/51a2e0497780c6b5846176667b2d3cba~tplv-tiktokx-cropcenter-q:300:300:q70.webp"
]
},
"avatar_thumb": {
"uri": "https://p19-common-sign.tiktokcdn.com/tos-alisg-avt-0068/51a2e0497780c6b5846176667b2d3cba~tplv-tiktokx-cropcenter-q:300:300:q70.webp",
"url_list": [
"https://p19-common-sign.tiktokcdn.com/tos-alisg-avt-0068/51a2e0497780c6b5846176667b2d3cba~tplv-tiktokx-cropcenter-q:300:300:q70.webp"
]
}
},
"statistics": {
"aweme_id": "7666535586920140052",
"collect_count": 13626,
"comment_count": 4155,
"play_count": 649203,
"share_count": 9951,
"digg_count": 112521,
"download_count": 15
},
"author_user_id": "7381072754353325063",
"create_time_utc": "2026-07-25T18:33:43.000Z",
"region": "SA",
"aweme_type": 150,
"is_ad": false,
"item_comment_settings": 0
}
],
"cursor": null
}
```
### `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` | string or 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` | string or null | Platform tracing block. Always `null` here. |
| `log_pb` | object or 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",
"has_more": false,
"status_code": 0,
"total": 4,
"comments": [
{
"aweme_id": "7612965843596479751",
"text": "Thx𓀠𓀠",
"create_time": 1772532161,
"user": {
"nickname": "ちい/Chii",
"unique_id": "artchiist",
"region": "JP",
"sec_uid": "MS4wLjABAAAANiBD2T6ao7u2cE5Xj1zRRiVjShx-oKRUIDUFgHqmbyUkUOH-bk4iehKJ7eOsUkrJ",
"signature": "⸝⋆꙳⟡.· ⋆ 𖦹ܾ 𖥧🪵🌿\n\n🗺ɪɴꜱᴛᴀɢʀᴀᴍ : @ artchiist\n\nꜱᴜʙ:@たいやきくん(ちい) 🚹: @壱",
"uid": "7093407411964986370",
"aweme_count": 0,
"favoriting_count": 0,
"follower_count": 0,
"following_count": 0,
"secret": false,
"total_favorited": 0,
"verified": false,
"avatar_larger": {
"uri": "https://p16-common-sign.tiktokcdn-us.com/tos-alisg-avt-0068/05fb1570b7fe0e2957d819ea183b2aa7~tplv-tiktokx-cropcenter-q:100:100:q70.jpeg",
"url_list": [
"https://p16-common-sign.tiktokcdn-us.com/tos-alisg-avt-0068/05fb1570b7fe0e2957d819ea183b2aa7~tplv-tiktokx-cropcenter-q:100:100:q70.jpeg"
]
}
},
"cid": "7612967610280805138",
"digg_count": 38,
"status": 1
}
],
"status_msg": "",
"cursor": null,
"extra": null,
"log_pb": null
}
```
## 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/@henripalms/video/7631128625017851138"}'
```
> 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` | string or null | |
| `transcript_vtt` | string or null | |
| `language` | string or null | |
| `is_auto_generated` | boolean or null | |
| `available_tracks` | array | |
```json theme={"system"}
{
"id": "7631128625017851138",
"language": "eng-US",
"transcript": "Next time you're in Tesco wondering if you should buy that chocolate bar, buy it. Because you could always be in an airport where a bar of chocolate cost £20",
"transcript_vtt": "WEBVTT\n\n\n00:00:00.180 --> 00:00:03.020\nNext time you're in Tesco wondering if you should buy that chocolate bar,\n\n00:00:03.021 --> 00:00:03.660\nbuy it.\n\n00:00:03.661 --> 00:00:08.520\nBecause you could always be in an airport where a bar of chocolate cost £20\n",
"url": "https://www.tiktok.com/@henripalms/video/7631128625017851138",
"available_tracks": [
{
"url": "https://v16m-webapp.tiktokcdn-us.com/372c64051b50340d45de1458b8cdc6ea/6a7934f8/video/tos/useast5/tos-useast5-v-0068c799-tx/102fcb7a5c304113be6f2f3a66041a78/",
"format": "webvtt",
"kind": "manual",
"language_code": "eng-US",
"language_name": "eng-US",
"is_auto_generated": false
}
],
"is_auto_generated": false
}
```
## 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` | string or 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": "2",
"has_more": true,
"page": 1,
"page_size": 20,
"total": 22,
"ads": [
{
"title": "Australia, Cozey is here with thoughtfully designed furniture and fast, free shipping from Sydney.",
"like_count": 288,
"video": {
"cover_url": "https://p16-common-sign.tiktokcdn.com/tos-alisg-p-0051c001-sg/ooZR8AfOUbQL4jNjDPgMIsFEN85IHqZJDfBMB1~tplv-noop.image",
"video_id": "v14033g50000d9mccjvog65u49opc4e0",
"video_link": "https://v16m-default.tiktokcdn.com/bd7683a10779a9d897b053e623ecdcd8/6a76e66f/video/tos/alisg/tos-alisg-ve-0051c001-sg/owbAcBEMnRDNNGgEZILWFXsBfeUQVqEDxGIPnv/",
"duration_seconds": 28.067,
"height": 1280,
"width": 720,
"video_links_by_quality": {
"1080p": "https://v16m-default.tiktokcdn.com/bd7683a10779a9d897b053e623ecdcd8/6a76e66f/video/tos/alisg/tos-alisg-ve-0051c001-sg/owbAcBEMnRDNNGgEZILWFXsBfeUQVqEDxGIPnv/",
"360p": "https://v16m-default.tiktokcdn.com/a2e11ad25488140a496e7ee5dfe997ba/6a76e66f/video/tos/alisg/tos-alisg-ve-0051c001-sg/o4dgnExPAIZDMeUqNXcBBWGpmEEKIQFsPBCbfD/",
"480p": "https://v16m-default.tiktokcdn.com/c52ac346b7bee8402068edfc9d994132/6a76e66f/video/tos/alisg/tos-alisg-ve-0051c001-sg/oQUD4GD7EDrgIMFgqfIAMjMfRZ8NBPDbZQBmOs/",
"540p": "https://v16m-default.tiktokcdn.com/eff8be47248c424b366f394eaf3949b4/6a76e66f/video/tos/alisg/tos-alisg-ve-0051c001-sg/oQFZMJOqbA2sBIPgE8OMTNjBUfZfI4MbDR4gQD/",
"720p": "https://v16m-default.tiktokcdn.com/23e90134042d71ac121a13265deca254/6a76e66f/video/tos/alisg/tos-alisg-ve-0051c001-sg/o8IcrNBqWbsxZFWDec9DmgQDUEBfAPI4GEGnEM/"
}
},
"ad_id": "7668717763499327508",
"brand_name": "cozey",
"industry_key": "label_21000000000",
"objective_key": "campaign_objective_traffic",
"cost_level": 2,
"ctr": 0.25,
"is_search_ad": true
}
]
}
```
### `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":"7668695930906099732"}'
```
**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` | array or 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` | object or null | |
| `interactive_time_analysis` | object or null | |
| `recommended_for_you` | boolean or null | |
```json theme={"system"}
{
"id": "7668695930906099732",
"ad_title": "Much needed curl refresh thanks to @Conair hair steamer 🩷✨ #curlyhair #haircare #routine #ad #Conair",
"brand_name": "Not Mention",
"creative_center_url": "https://ads.tiktok.com/business/creativecenter/ads/detail/7668695930906099732",
"industry_key": "label_16100000000",
"landing_page": "https://www.tiktok.com/t/ZT9hYLPTgToKJ-A3JyY/",
"objective_key": "campaign_objective_reach",
"source": "Others",
"comment": 143,
"cost": 2,
"ctr": 0.45,
"favorite": false,
"has_summary": false,
"is_search": false,
"like": 625,
"share": 4,
"source_key": 73,
"voice_over": false,
"video_info": {
"video_url": {
"540p": "https://v16m-default.tiktokcdn.com/81b0ac1be7d9002f4299da4d639f7af2/6a76e674/video/tos/maliva/tos-maliva-ve-0068c799-us/oYVOGpwPEborAFpfGgSQVgDsatGzBADgEIvfRB/",
"720p": "https://v16m-default.tiktokcdn.com/12365586084c8ed438fb503b2c12039d/6a76e674/video/tos/maliva/tos-maliva-ve-0068c799-us/oAwjIASRVEBrPfDGDXgFBzvSQfsVptEBwgGgOA/"
},
"cover": "https://p16-common-sign.tiktokcdn.com/tos-maliva-p-0068c799-us/o0fIICjHgwWiDB4OApAgIEKswQipB0A15jBpGi~tplv-noop.image",
"vid": "v12044gd0000d77b3bfog65g3u1a60g0",
"duration": 32.467,
"height": 1280,
"width": 720
},
"objectives": [
{
"label": "campaign_objective_reach",
"value": 5
}
],
"country_code": [
"US"
],
"highlight_text": "",
"detail_analysis": null,
"interactive_time_analysis": null,
"keyword_list": null,
"recommended_for_you": null,
"pattern_label": []
}
```
`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": {
"full_name": "NASA",
"id": "528817151",
"username": "nasa",
"biography": "Making the seemingly impossible, possible. ✨",
"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",
"category_enum": "GOVERNMENT_ORGANIZATION",
"eimu_id": "118750106179205",
"external_url": "https://www.nasa.gov/",
"external_url_linkshimmed": "https://l.instagram.com/",
"fbid": "17841401474538262",
"profile_pic_url": "https://scontent-phl2-1.cdninstagram.com/v/t51.2885-19/29090066_159271188110124_1152068159029641216_n.jpg",
"profile_pic_url_hd": "https://scontent-phl2-1.cdninstagram.com/v/t51.2885-19/29090066_159271188110124_1152068159029641216_n.jpg",
"blocked_by_viewer": false,
"country_block": false,
"followed_by_viewer": false,
"follows_viewer": false,
"has_ar_effects": false,
"has_blocked_viewer": false,
"has_channel": false,
"has_clips": true,
"has_guides": false,
"has_onboarded_to_text_post_app": true
}
}
}
```
`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":"13460080"}'
```
**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` | string or null | |
| `external_url` | string | |
| `bio_links` | array | |
| `pronouns` | array | |
| `fbid_v2` | string | |
| `is_embeds_disabled` | boolean | |
| `show_account_transparency_details` | boolean | |
| `transparency_label` | string or null | |
| `transparency_product` | string or null | |
| `address_street` | string | |
| `city_name` | string or null | |
| `zip` | string or null | |
| `is_regulated_c18` | boolean | |
| `has_chaining` | boolean | |
| `total_clips_count` | number | |
```json theme={"system"}
{
"full_name": "Nike",
"id": "13460080",
"username": "nike",
"account_type": "business",
"address_street": "{\"city_name\": \"Beaverton, Oregon\", \"city_id\": 108410602520455, \"latitude\": 45.5076448, \"longitude\": -122.8269159, \"street_address\": \"One Bowerman Dr\", \"zip_code\": \"97005\"}",
"biography": "Just Do It.",
"external_url": "http://empli.fi/nike",
"fbid_v2": "17841400602400210",
"pk": "13460080",
"profile_pic_url": "https://scontent-den2-1.cdninstagram.com/v/t51.82787-19/551608484_18567162979020081_1135468084872726555_n.jpg",
"follower_count": 291586953,
"following_count": 264,
"has_chaining": false,
"is_business": true,
"is_embeds_disabled": false,
"is_private": false,
"is_professional_account": true,
"is_regulated_c18": false,
"is_verified": true,
"media_count": 1667,
"show_account_transparency_details": true,
"success": true,
"total_clips_count": 0,
"bio_links": [
{
"url": "http://empli.fi/nike",
"link_type": "external",
"lynx_url": "https://l.instagram.com/"
}
],
"hd_profile_pic_url_info": {
"url": "https://scontent-den2-1.cdninstagram.com/v/t51.82787-19/551608484_18567162979020081_1135468084872726555_n.jpg"
},
"biography_with_entities": {
"raw_text": "Just Do It.",
"entities": []
},
"category": null,
"city_name": null,
"transparency_label": null,
"transparency_product": null,
"zip": null,
"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