# SocialCrawl API — tiktok endpoints
# Base URL: https://www.socialcrawl.dev
# Auth: x-api-key header
# Full docs: https://www.socialcrawl.dev/docs/tiktok

## GET /v1/tiktok/profile
Get TikTok user profile
Credit cost: 1 (standard)
Parameters:
- handle (required) — TikTok username without the @ symbol
curl "https://www.socialcrawl.dev/v1/tiktok/profile?handle=charlidamelio" \
  -H "x-api-key: sc_your_api_key_here"

## GET /v1/tiktok/profile/videos
List TikTok user videos
Credit cost: 1 (standard)
Parameters:
- handle (required) — TikTok username without the @ symbol
- user_id (optional, string) — TikTok user id. Use this for faster responses.
- sort_by (optional, enum: latest | popular) — What to sort by
- max_cursor (optional, string) — Cursor to get more videos. Get 'max_cursor' from previous response.
- region (optional, string) — Region (Country) you want the proxy in. Defaults to US.
- trim (optional, boolean) — Set to true for a trimmed down version of the response
curl "https://www.socialcrawl.dev/v1/tiktok/profile/videos?handle=charlidamelio" \
  -H "x-api-key: sc_your_api_key_here"

## GET /v1/tiktok/post
Get TikTok post details
Credit cost: 1 (standard)
Parameters:
- url (required) — Full URL of the TikTok video
- get_transcript (optional, boolean) — Get transcript of the video
- region (optional, string) — Region of the proxy. Sometimes you'll need to specify the region if you're not getting a response. Commonly for videos from the Phillipines, in which case you'd use 'PH'. Use 2 letter country codes like US, GB, FR, etc
- trim (optional, boolean) — Set to true to get a trimmed response
- download_media (optional, boolean) — Set to true to download the video/images and get back permanent Supabase URLs. Costs 10 credits if media is found, 1 credit otherwise.
curl "https://www.socialcrawl.dev/v1/tiktok/post?url=https://www.tiktok.com/@charlidamelio/video/7321485815660738859" \
  -H "x-api-key: sc_your_api_key_here"

## GET /v1/tiktok/post/comments
List TikTok post comments
Credit cost: 1 (standard)
Parameters:
- url (required) — Full URL of the TikTok video to fetch comments for
- cursor (optional, integer) — Cursor to get more comments. Get 'cursor' from previous response.
- trim (optional, boolean) — Set to true to get a trimmed response
curl "https://www.socialcrawl.dev/v1/tiktok/post/comments?url=https://www.tiktok.com/@charlidamelio/video/7321485815660738859" \
  -H "x-api-key: sc_your_api_key_here"

## GET /v1/tiktok/video/comment/replies
List TikTok comment replies
Credit cost: 1 (standard)
Parameters:
- comment_id (required) — TikTok comment ID. This is the cid from the comments endpoint.
- url (required) — TikTok video URL. This is the url from the comments endpoint.
- cursor (optional, integer) — Cursor to get more replies. Get 'cursor' from previous response.
curl "https://www.socialcrawl.dev/v1/tiktok/video/comment/replies?comment_id=7623828115408274207" \
  -H "x-api-key: sc_your_api_key_here"

## GET /v1/tiktok/search
Search TikTok videos by keyword
Credit cost: 1 (standard)
Parameters:
- query (required) — Search keyword or phrase to find TikTok videos
- date_posted (optional, enum: yesterday | this-week | this-month | last-3-months | last-6-months | all-time) — Time Frame
- sort_by (optional, enum: relevance | most-liked | date-posted) — Sort by
- region (optional, string) — Note, this doesn't filter the tiktoks only in a specfic region, it puts the proxy there. Use it in case you want to scrape posts only available for some country. Use 2 letter country codes like US, GB, FR, etc
- cursor (optional, integer) — Cursor to get more videos. Get 'cursor' from previous response.
- trim (optional, boolean) — Set to true to get a trimmed response
curl "https://www.socialcrawl.dev/v1/tiktok/search?query=cooking recipes" \
  -H "x-api-key: sc_your_api_key_here"

## GET /v1/tiktok/trending
Get TikTok trending feed
Credit cost: 5 (advanced)
Parameters:
- region (required) — ISO 3166-1 alpha-2 country code (e.g., US, GB, KR)
- trim (optional, boolean) — Set to true to get a trimmed response.
curl "https://www.socialcrawl.dev/v1/tiktok/trending?region=US" \
  -H "x-api-key: sc_your_api_key_here"

## GET /v1/tiktok/search/hashtag
Search TikTok by hashtag
Credit cost: 1 (standard)
Parameters:
- hashtag (required) — Hashtag to search for without the # symbol
- region (optional, string) — Region the proxy will be set to. Note: this isn't going to grab you all tiktoks from this region, you're just setting the proxy there.
- cursor (optional, integer) — Cursor to get more videos. Get 'cursor' from previous response.
- trim (optional, boolean) — Set to true to get a trimmed response
curl "https://www.socialcrawl.dev/v1/tiktok/search/hashtag?hashtag=fyp" \
  -H "x-api-key: sc_your_api_key_here"

## GET /v1/tiktok/search/top
TikTok top search results
Credit cost: 1 (standard)
Parameters:
- query (required) — Search keyword or phrase
- publish_time (optional, enum: yesterday | this-week | this-month | last-3-months | last-6-months | all-time) — Time Frame TikTok was posted
- sort_by (optional, enum: relevance | most-liked | date-posted) — Sort by
- region (optional, string) — Note, this doesn't filter the tiktoks only in a specfic region, it puts the proxy there. Use it in case you want to scrape posts only available for some country. Use 2 letter country codes like US, GB, FR, etc
- cursor (optional, integer) — Cursor to get more videos. Get 'cursor' from previous response.
curl "https://www.socialcrawl.dev/v1/tiktok/search/top?query=dance challenge" \
  -H "x-api-key: sc_your_api_key_here"

## GET /v1/tiktok/search/users
Search TikTok users
Credit cost: 1 (standard)
Parameters:
- query (required) — Search keyword or phrase to find TikTok users
- cursor (optional, integer) — Cursor to get more users. Get 'cursor' from previous response.
- trim (optional, boolean) — Set to true to get a trimmed response
curl "https://www.socialcrawl.dev/v1/tiktok/search/users?query=cooking" \
  -H "x-api-key: sc_your_api_key_here"

## GET /v1/tiktok/user/audience
Get TikTok user audience demographics
Credit cost: 5 (advanced)
Parameters:
- handle (required) — TikTok username without the @ symbol
curl "https://www.socialcrawl.dev/v1/tiktok/user/audience?handle=charlidamelio" \
  -H "x-api-key: sc_your_api_key_here"

## GET /v1/tiktok/user/followers
List TikTok user followers
Credit cost: 1 (standard)
Parameters:
- handle (optional, string) — TikTok username without the @ symbol
- user_id (optional, string) — User id. Use this for faster response times.
- min_time (optional, integer) — Used to paginate. Get 'min_time' from previous response.
- trim (optional, boolean) — Set to true to get a trimmed response
- Constraint: one of handle, user_id (at least one required)
curl "https://www.socialcrawl.dev/v1/tiktok/user/followers" \
  -H "x-api-key: sc_your_api_key_here"

## GET /v1/tiktok/user/following
List TikTok user following
Credit cost: 1 (standard)
Parameters:
- handle (required) — TikTok username without the @ symbol
- min_time (optional, integer) — Used to paginate. Get 'min_time' from previous response.
- trim (optional, boolean) — Set to true to get a trimmed response
curl "https://www.socialcrawl.dev/v1/tiktok/user/following?handle=charlidamelio" \
  -H "x-api-key: sc_your_api_key_here"

## GET /v1/tiktok/user/live
Get TikTok user live stream
Credit cost: 1 (standard)
Parameters:
- handle (required) — TikTok username without the @ symbol
curl "https://www.socialcrawl.dev/v1/tiktok/user/live?handle=charlidamelio" \
  -H "x-api-key: sc_your_api_key_here"

## GET /v1/tiktok/post/transcript
Get TikTok video transcript
Credit cost: 10 (premium)
Parameters:
- url (required) — Full URL of the TikTok video
- language (optional, string) — Language of the transcript. 2 letter language code, ie 'en', 'es', 'fr', 'de', 'it', 'ja', 'ko', 'zh'
- use_ai_as_fallback (optional, string) — Set to 'true' to use AI as a fallback to get the transcript if the transcript is not found. Costs 10 credits to use this feature. And only if the video is under 2 minutes.
curl "https://www.socialcrawl.dev/v1/tiktok/post/transcript?url=https://www.tiktok.com/@charlidamelio/video/7321485815660738859" \
  -H "x-api-key: sc_your_api_key_here"

## GET /v1/tiktok/song
Get TikTok song details
Credit cost: 1 (standard)
Parameters:
- clipId (required) — TikTok sound/song clip ID
curl "https://www.socialcrawl.dev/v1/tiktok/song?clipId=7252403792087040774" \
  -H "x-api-key: sc_your_api_key_here"

## GET /v1/tiktok/song/videos
List TikTok videos using a song
Credit cost: 1 (standard)
Parameters:
- clipId (optional, string) — TikTok sound/song clip ID
- cursor (optional, integer) — The cursor to get the next page of results.
curl "https://www.socialcrawl.dev/v1/tiktok/song/videos" \
  -H "x-api-key: sc_your_api_key_here"

## GET /v1/tiktok/songs/popular
Get popular TikTok songs
Credit cost: 5 (advanced)
Parameters:
- page (optional, integer) — Page number
- timePeriod (optional, enum: 7 | 30 | 130) — Time period to get popular songs from
- rankType (optional, enum: popular | surging) — Get popular or surging songs
- newOnBoard (optional, boolean) — New to top 100
- commercialMusic (optional, boolean) — Approved for business use?
- countryCode (optional, enum: AR | AU | AT | BH | BD | BY | BE | BR | BG | KH | CA | CL | CO | HR | CZ | DK | EG | EE | FI | FR | DE | GR | HU | IS | ID | IQ | IE | IL | IT | JP | JO | KZ | KW | LV | LB | LT | LU | MO | MY | MX | MA | MM | NL | NZ | NG | NO | OM | PK | PE | PH | PL | PT | QA | RO | SA | SG | SK | ZA | KR | ES | SE | CH | TW | TH | TR | UA | AE | GB | US | UZ | VN) — Country code to get popular songs from
curl "https://www.socialcrawl.dev/v1/tiktok/songs/popular" \
  -H "x-api-key: sc_your_api_key_here"

## GET /v1/tiktok/creators/popular
Get popular TikTok creators
Credit cost: 5 (advanced)
Parameters:
- page (optional, integer) — Page number
- sortBy (optional, enum: engagement | follower | avg_views) — Sort creators by engagement, follower count, or average views
- followerCount (optional, enum: 10K-100K | 100K-1M | 1M-10M | 10M+) — Filter by follower count range
- creatorCountry (optional, enum: AU | BR | CA | EG | FR | DE | ID | IL | IT | JP | MY | PH | RU | SA | SG | KR | ES | TW | TH | TR | AE | GB | US | VN) — Country code of the creator
- audienceCountry (optional, enum: AU | BR | CA | EG | FR | DE | ID | IL | IT | JP | MY | PH | RU | SA | SG | KR | ES | TW | TH | TR | AE | GB | US | VN) — Country code of the audience/follower
curl "https://www.socialcrawl.dev/v1/tiktok/creators/popular" \
  -H "x-api-key: sc_your_api_key_here"

## GET /v1/tiktok/hashtags/popular
Get popular TikTok hashtags
Credit cost: 5 (advanced)
Parameters:
- period (optional, enum: 7 | 30 | 120) — Time period in days (7, 30, or 120)
- page (optional, integer) — Page number
- countryCode (optional, enum: AU | BR | CA | EG | FR | DE | ID | IL | IT | JP | MY | PH | RU | SA | SG | KR | ES | TW | TH | TR | AE | GB | US | VN) — Country code to get popular hashtags from
- newOnBoard (optional, boolean) — Show only newly trending hashtags
- industry (optional, enum: apparel-and-accessories | baby-kids-and-maternity | beauty-and-personal-care | business-services | education | financial-services | food-and-beverage | games | health | home-improvement | household-products | life-services | news-and-entertainment | pets | sports-and-outdoor | tech-and-electronics | travel | vehicle-and-transportation) — Industry to get popular hashtags from.
curl "https://www.socialcrawl.dev/v1/tiktok/hashtags/popular" \
  -H "x-api-key: sc_your_api_key_here"

## GET /v1/tiktok/videos/popular
Get popular TikTok videos
Credit cost: 5 (advanced)
Parameters:
- period (optional, enum: 7 | 30) — Time period in days (7 or 30)
- page (optional, integer) — Page number
- orderBy (optional, enum: like | hot | comment | repost) — Sort videos by likes, views (hot), comments, or reposts
- countryCode (optional, enum: AU | BR | CA | EG | FR | DE | ID | IL | IT | JP | MY | PH | RU | SA | SG | KR | ES | TW | TH | TR | AE | GB | US | VN) — Country code to get popular videos from
curl "https://www.socialcrawl.dev/v1/tiktok/videos/popular" \
  -H "x-api-key: sc_your_api_key_here"

## GET /v1/tiktok/shop/product
Get TikTok Shop product details
Credit cost: 1 (standard)
Parameters:
- url (required) — Full URL of the TikTok Shop product page
- region (optional, string) — Region the proxy will be set to so you can access products from that country. Use 2 letter country codes like US, GB, FR, etc. For England, don't use UK, use GB.
curl "https://www.socialcrawl.dev/v1/tiktok/shop/product?url=https://www.tiktok.com/@shop/product/1234567890" \
  -H "x-api-key: sc_your_api_key_here"

## GET /v1/tiktok/shop/product/reviews
List TikTok Shop product reviews
Credit cost: 1 (standard)
Parameters:
- url (optional, string) — Full URL of the TikTok Shop product page
- product_id (optional, string) — The ID of the product (required if url is not provided)
- page (optional, integer) — The page number of the reviews
- Constraint: one of url, product_id (at least one required)
curl "https://www.socialcrawl.dev/v1/tiktok/shop/product/reviews" \
  -H "x-api-key: sc_your_api_key_here"

## GET /v1/tiktok/shop/products
List TikTok Shop products
Credit cost: 1 (standard)
Parameters:
- url (required) — Full URL of the TikTok Shop page
- cursor (optional, string) — Cursor parameter from the previous response to retrieve the next page of products. Omit for the first page.
- region (optional, enum: US | GB | DE | FR | IT | ID | MY | MX | PH | SG | ES | TH | VN | BR | JP | IE) — Region to get shop products from. Defaults to US if not provided.
curl "https://www.socialcrawl.dev/v1/tiktok/shop/products?url=https://www.tiktok.com/@shop/1234567890" \
  -H "x-api-key: sc_your_api_key_here"

## GET /v1/tiktok/shop/search
Search TikTok Shop products
Credit cost: 1 (standard)
Parameters:
- query (required) — Search keyword or phrase to find TikTok Shop products
- page (optional, integer) — Page number to retrieve
- region (optional, enum: US | GB | DE | FR | IT | ID | MY | MX | PH | SG | ES | TH | VN | BR | JP | IE) — Region to search shop products in.
curl "https://www.socialcrawl.dev/v1/tiktok/shop/search?query=phone case" \
  -H "x-api-key: sc_your_api_key_here"

## GET /v1/tiktok/user/showcase
List TikTok user showcase products
Credit cost: 1 (standard)
Parameters:
- handle (required) — The handle of the user
- region (optional, string) — Region to put the proxy in
- cursor (optional, string) — The cursor to the next page of products
curl "https://www.socialcrawl.dev/v1/tiktok/user/showcase?handle=mrtiktokreviews" \
  -H "x-api-key: sc_your_api_key_here"