# Social Fetch API - TikTok endpoints
# Base URL: https://api.socialfetch.dev
# Auth: x-api-key header (sfk_...)
# Full catalog: https://www.socialfetch.dev/llms-endpoints.txt | JSON: https://www.socialfetch.dev/llms.json
# Docs hub: https://www.socialfetch.dev/docs/api | OpenAPI: https://www.socialfetch.dev/openapi.json

24 documented TikTok operations. Do not invent paths - only the routes below (and their linked markdown pages) are supported.

## GET /v1/tiktok/profiles/{handle}
Get TikTok profile
Credit cost: 1 credit per successful request.
Docs: https://www.socialfetch.dev/docs/api/v1/tiktok/profiles/handle/get.mdx
SDK: client.tiktok.getProfile({ handle })
Parameters:
- handle (required, string) - TikTok handle to look up, with or without a leading @.
Outcome field: `data.lookupStatus` in `found`, `private`, `not_found`
curl "https://api.socialfetch.dev/v1/tiktok/profiles/charlidamelio" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/tiktok/profiles/{handle}/videos
List TikTok profile videos
Credit cost: 1 credit per successful request.
Docs: https://www.socialfetch.dev/docs/api/v1/tiktok/profiles/handle/videos/get.mdx
SDK: client.tiktok.getProfileVideos({ handle, cursor? })
Parameters:
- handle (required, string) - TikTok handle whose videos should be listed.
- sortBy (optional, string, enum: latest | popular) - Optional sort order for the returned TikTok videos.
- cursor (optional, string) - Pagination cursor returned by a previous response.
- userId (optional, string) - Optional TikTok user id to speed up the request.
- region (optional, string) - Optional ISO 3166-1 country code for the request.
- trim (optional, boolean) - Optional flag for a smaller response with fewer fields.
Pagination: send query `cursor` from prior `data.page.nextCursor`; stop when `data.page.hasMore` is false.
Empty results: An empty `data.videos` array can mean no videos in the selected sort window, a private profile, or other cases—there is no `lookupStatus` field on this route.
Disambiguation: Call `GET /v1/tiktok/profiles/{handle}` when you need explicit `lookupStatus` including `private` or `not_found` before interpreting an empty video list.
curl "https://api.socialfetch.dev/v1/tiktok/profiles/charlidamelio/videos" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/tiktok/profiles/{handle}/followers
List TikTok profile followers
Credit cost: 1 credit per successful request.
Docs: https://www.socialfetch.dev/docs/api/v1/tiktok/profiles/handle/followers/get.mdx
SDK: client.tiktok.getProfileFollowers({ handle, cursor? })
Parameters:
- handle (required, string) - TikTok handle whose followers should be listed.
- cursor (optional, string) - Pagination cursor returned by a previous response.
- userId (optional, string) - Optional TikTok user id to speed up the request.
- trim (optional) - Optional flag for a smaller response with fewer fields.
Pagination: send query `cursor` from prior `data.page.nextCursor`; stop when `data.page.hasMore` is false.
Outcome field: `data.lookupStatus` in `found`, `hidden`, `private`, `not_found`
curl "https://api.socialfetch.dev/v1/tiktok/profiles/charlidamelio/followers" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/tiktok/profiles/{handle}/following
List TikTok profile following
Credit cost: 1 credit per successful request.
Docs: https://www.socialfetch.dev/docs/api/v1/tiktok/profiles/handle/following/get.mdx
SDK: client.tiktok.getProfileFollowing({ handle, cursor? })
Parameters:
- handle (required, string) - TikTok handle whose following list should be listed.
- cursor (optional, string) - Pagination cursor returned by a previous response.
- trim (optional, boolean) - Optional flag for a smaller response with fewer fields.
Pagination: send query `cursor` from prior `data.page.nextCursor`; stop when `data.page.hasMore` is false.
Outcome field: `data.lookupStatus` in `found`, `hidden`, `private`, `not_found`
curl "https://api.socialfetch.dev/v1/tiktok/profiles/charlidamelio/following" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/tiktok/profiles/{handle}/region
Get TikTok profile region
Credit cost: 1 credit per successful request.
Docs: https://www.socialfetch.dev/docs/api/v1/tiktok/profiles/handle/region/get.mdx
SDK: client.tiktok.getProfileRegion({ handle })
Parameters:
- handle (required, string) - TikTok handle to look up, with or without a leading @.
Outcome field: `data.lookupStatus` in `found`, `not_found`
curl "https://api.socialfetch.dev/v1/tiktok/profiles/charlidamelio/region" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/tiktok/profiles/{handle}/audience
Get TikTok profile audience
Credit cost: 30 credits per successful request.
Docs: https://www.socialfetch.dev/docs/api/v1/tiktok/profiles/handle/audience/get.mdx
SDK: client.tiktok.getProfileAudience({ handle })
Parameters:
- handle (required, string) - TikTok handle to look up, with or without a leading @.
Outcome field: `data.lookupStatus` in `found`, `not_found`
curl "https://api.socialfetch.dev/v1/tiktok/profiles/charlidamelio/audience" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/tiktok/profiles/{handle}/live
Get TikTok live stream
Credit cost: 1 credit per successful request.
Docs: https://www.socialfetch.dev/docs/api/v1/tiktok/profiles/handle/live/get.mdx
SDK: client.tiktok.getProfileLive({ handle })
Parameters:
- handle (required, string) - TikTok handle to look up, with or without a leading @.
Outcome field: `data.lookupStatus` in `found`, `not_found`
curl "https://api.socialfetch.dev/v1/tiktok/profiles/charlidamelio/live" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/tiktok/users/search
Search TikTok users
Credit cost: 1 credit per successful request.
Docs: https://www.socialfetch.dev/docs/api/v1/tiktok/users/search/get.mdx
SDK: client.tiktok.searchUsers({ query })
Parameters:
- query (required, string) - Search query text for TikTok users.
- cursor (optional, string) - Opaque pagination cursor returned by a previous response.
Pagination: send query `cursor` from prior `data.page.nextCursor`; stop when `data.page.hasMore` is false.
curl "https://api.socialfetch.dev/v1/tiktok/users/search?query=mrbeast" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/tiktok/search
Search TikTok videos
Credit cost: 1 credit per successful request.
Docs: https://www.socialfetch.dev/docs/api/v1/tiktok/search/get.mdx
SDK: client.tiktok.searchVideos({ query: "web scraping" })
Parameters:
- query (required, string) - Search query text for TikTok videos.
- datePosted (optional, string, enum: yesterday | this-week | this-month | last-3-months | last-6-months | all-time) - Optional upload date filter for video results.
- sortBy (optional, string, enum: relevance | most-liked | date-posted) - Optional sort order for search results.
- region (optional, string) - Optional two-letter ISO 3166-1 country code for localized search results.
- cursor (optional, string) - Opaque pagination cursor returned by a previous response.
- trim (optional, boolean) - When true, returns a smaller response with fewer fields.
Pagination: send query `cursor` from prior `data.page.nextCursor`; stop when `data.page.hasMore` is false.
curl "https://api.socialfetch.dev/v1/tiktok/search?query=web scraping" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/tiktok/search/hashtags
Search TikTok by hashtag
Credit cost: 1 credit per successful request.
Docs: https://www.socialfetch.dev/docs/api/v1/tiktok/search/hashtags/get.mdx
SDK: client.tiktok.searchHashtags({ hashtag: "fyp" })
Parameters:
- hashtag (required, string) - Hashtag to search for. A leading # is optional.
- region (optional, string) - Optional ISO 3166-1 country code for the request. This sets the proxy region and does not filter results to that country only.
- cursor (optional, string) - Pagination cursor returned by a previous response.
- trim (optional, boolean) - Whether to request a smaller response with fewer fields.
Pagination: send query `cursor` from prior `data.page.nextCursor`; stop when `data.page.hasMore` is false.
Disambiguation: Use `data.page.hasMore` and `data.page.nextCursor` for pagination. Repeat the same hashtag and filters when requesting the next page.
curl "https://api.socialfetch.dev/v1/tiktok/search/hashtags?hashtag=trending" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/tiktok/videos
Get TikTok video
Credit cost: 1 credit base, +10 with `downloadMedia`. Up to 11 credits max.
Docs: https://www.socialfetch.dev/docs/api/v1/tiktok/videos/get.mdx
SDK: client.tiktok.getVideo({ url })
Parameters:
- url (required, string) - Link to the video or photo post.
- region (optional, string) - Optional ISO 3166-1 country code used to route the request when needed.
- trim (optional) - When true, returns a smaller response with fewer fields.
- downloadMedia (optional) - When true, includes hosted CDN URLs in `downloads` when available. Adds 10 credits (11 total with the base lookup) on successful lookups, even if `downloads` is empty.
- getTranscript (optional) - When true, includes the video transcript (WEBVTT) in `transcript` when one is available.
Outcome field: `data.lookupStatus` in `found`, `not_found`
curl "https://api.socialfetch.dev/v1/tiktok/videos?url=https://www.tiktok.com/@mrbeast/video/7596844935442189598" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/tiktok/videos/comments
List TikTok video comments
Credit cost: 1 credit per successful request.
Docs: https://www.socialfetch.dev/docs/api/v1/tiktok/videos/comments/get.mdx
SDK: client.tiktok.getVideoComments({ url })
Parameters:
- url (required, string) - Link to the TikTok video whose comments should be listed.
- cursor (optional, string) - Opaque cursor from a previous response to fetch the next page.
- trim (optional) - When true, returns a smaller response with fewer fields.
Pagination: send query `cursor` from prior `data.page.nextCursor`; stop when `data.page.hasMore` is false.
Outcome field: `data.lookupStatus` in `found`, `not_found`
Disambiguation: Cursor pagination with variable page size — use `data.page.hasMore` and `data.page.nextCursor`; do not assume a fixed number of comments per page or loop on `totalComments` alone.
curl "https://api.socialfetch.dev/v1/tiktok/videos/comments?url=https://www.tiktok.com/@mrbeast/video/7596844935442189598" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/tiktok/videos/comments/replies
List TikTok comment replies
Credit cost: 1 credit per successful request.
Docs: https://www.socialfetch.dev/docs/api/v1/tiktok/videos/comments/replies/get.mdx
SDK: client.tiktok.getVideoCommentReplies({ commentId, url })
Parameters:
- commentId (required, string) - Parent comment id from List TikTok video comments (`data.comments[].id`).
- url (required, string) - Link to the TikTok video that contains the parent comment.
- cursor (optional, string) - Opaque cursor from a previous response to fetch the next page.
Pagination: send query `cursor` from prior `data.page.nextCursor`; stop when `data.page.hasMore` is false.
Outcome field: `data.lookupStatus` in `found`, `not_found`
Disambiguation: Requires parent `commentId` from List TikTok video comments plus the same video `url`. Paginate with `data.page.hasMore` and `data.page.nextCursor`; do not assume a fixed page size.
curl "https://api.socialfetch.dev/v1/tiktok/videos/comments/replies?commentId=7623828115408274207&url=https://www.tiktok.com/@mrbeast/video/7596844935442189598" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/tiktok/videos/transcript
Get TikTok video transcript
Credit cost: 1 credit base, +10 with `useAiFallback`. Up to 11 credits max.
Docs: https://www.socialfetch.dev/docs/api/v1/tiktok/videos/transcript/get.mdx
SDK: client.tiktok.getVideoTranscript({ url })
Parameters:
- url (required, string) - Link to the TikTok video whose transcript should be returned.
- language (optional, string) - Optional two-letter language code to request a transcript in a specific language when available.
- useAiFallback (optional) - When true, uses Social Fetch's AI fallback when a transcript is not otherwise available. Adds 10 credits on completed lookups (11 total with the base lookup).
Outcome field: `data.lookupStatus` in `found`, `not_found`
curl "https://api.socialfetch.dev/v1/tiktok/videos/transcript?url=https://www.tiktok.com/@mrbeast/video/7596844935442189598" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/tiktok/feed/trending
List TikTok trending feed
Credit cost: 1 credit per successful request.
Docs: https://www.socialfetch.dev/docs/api/v1/tiktok/feed/trending/get.mdx
SDK: client.tiktok.listTrendingFeed({ region: 'US' })
Parameters:
- region (required, string) - Two-letter ISO 3166-1 country code for the request.
- trim (optional) - When true, requests a smaller response with fewer optional fields.
Disambiguation: Repeat the same request for a fresh trending batch. New and overlapping posts are both possible. No cursor or page parameters.
curl "https://api.socialfetch.dev/v1/tiktok/feed/trending?region=US" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/tiktok/songs
Get TikTok song
Credit cost: 1 credit per successful request.
Docs: https://www.socialfetch.dev/docs/api/v1/tiktok/songs/get.mdx
SDK: client.tiktok.getSong({ id })
Parameters:
- id (required, string) - TikTok song or sound id. Use the trailing id from a music page URL, or `music.id` from a video lookup.
Outcome field: `data.lookupStatus` in `found`, `not_found`
curl "https://api.socialfetch.dev/v1/tiktok/songs?id=7439295283975702544" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/tiktok/music/{clipId}/videos
List TikTok music videos
Credit cost: 1 credit per successful request.
Docs: https://www.socialfetch.dev/docs/api/v1/tiktok/music/clipid/videos/get.mdx
SDK: client.tiktok.listMusicVideos({ clipId: "7439295283975702544" })
Parameters:
- clipId (required, string) - TikTok music clip id whose videos should be listed.
- cursor (optional, string) - Pagination cursor returned by a previous response.
Pagination: send query `cursor` from prior `data.page.nextCursor`; stop when `data.page.hasMore` is false.
Empty results: An empty `data.videos` array can mean no public videos use this music clip, or other cases—there is no `lookupStatus` field on this route.
curl "https://api.socialfetch.dev/v1/tiktok/music/7439295283975702544/videos" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/tiktok/shop/products/search
Search TikTok Shop products
Credit cost: 1 credit per successful request.
Docs: https://www.socialfetch.dev/docs/api/v1/tiktok/shop/products/search/get.mdx
SDK: client.tiktok.searchShopProducts({ query })
Parameters:
- query (required, string) - Search query text for TikTok Shop products.
- page (optional) - 1-based results page number. Omit to request the first page. Pagination is page-based.
- region (optional, string, enum: US | GB | DE | FR | IT | ID | MY | MX | PH | SG | ES | TH | VN | BR | JP | IE) - Optional country or region code for the product search catalog.
curl "https://api.socialfetch.dev/v1/tiktok/shop/products/search?query=shoes" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/tiktok/shop/products
List TikTok Shop store products
Credit cost: 1 credit per successful request.
Docs: https://www.socialfetch.dev/docs/api/v1/tiktok/shop/products/get.mdx
SDK: client.tiktok.listShopProducts({ url })
Parameters:
- url (required, string) - Public TikTok Shop store URL whose products should be listed.
- cursor (optional, string) - Pagination cursor from a previous response. Omit to request the first page.
- region (optional, string, enum: US | GB | DE | FR | IT | ID | MY | MX | PH | SG | ES | TH | VN | BR | JP | IE) - Optional region code for the shop catalog. When omitted, the default catalog region is US.
Pagination: send query `cursor` from prior `data.page.nextCursor`; stop when `data.page.hasMore` is false.
Outcome field: `data.lookupStatus` in `found`, `not_found`
curl "https://api.socialfetch.dev/v1/tiktok/shop/products?url=https://www.tiktok.com/shop/store/goli-nutrition/7495794203056835079" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/tiktok/products
Get TikTok Shop product
Credit cost: 1 credit per successful request.
Docs: https://www.socialfetch.dev/docs/api/v1/tiktok/products/get.mdx
SDK: client.tiktok.getProduct({ url })
Parameters:
- url (required, string) - Public TikTok Shop product detail page URL for the product to retrieve.
- region (optional, string, enum: US | GB | DE | FR | IT | ID | MY | MX | PH | SG | ES | TH | VN | BR | JP | IE) - Optional country or region code for the product catalog. When omitted, the default catalog region applies.
curl "https://api.socialfetch.dev/v1/tiktok/products?url=https://www.tiktok.com/shop/pdp/goli-ashwagandha-gummies-with-vitamin-d-ksm-66-vegan-non-gmo/1729587769570529799" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/tiktok/products/reviews
List TikTok Shop product reviews
Credit cost: 1 credit per successful request.
Docs: https://www.socialfetch.dev/docs/api/v1/tiktok/products/reviews/get.mdx
SDK: client.tiktok.getProductReviews({ url: 'https://www.tiktok.com/shop/pdp/...' })
Parameters:
- url (optional, string) - Public TikTok Shop product detail page URL for the product whose reviews should be listed.
- productId (optional, string) - TikTok Shop product identifier. Provide this instead of `url` when you already know the product id.
- region (optional, string, enum: US | GB | DE | FR | IT | ID | MY | MX | PH | SG | ES | TH | VN | BR | JP | IE) - Optional country or region code for the product review catalog. When omitted, the default catalog region applies.
- page (optional) - 1-based review page number. Omit to request the first page.
Outcome field: `data.lookupStatus` in `found`, `not_found`
curl "https://api.socialfetch.dev/v1/tiktok/products/reviews?url=https://www.tiktok.com/shop/pdp/cat-nail-clipper-by-potaroma-adjustable-sizes-built-in-file-safe-for-kittens-cats/1731578642912612516" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/tiktok/profiles/{handle}/showcase-products
List TikTok profile showcase products
Credit cost: 1 credit per successful request.
Docs: https://www.socialfetch.dev/docs/api/v1/tiktok/profiles/handle/showcase-products/get.mdx
SDK: client.tiktok.getProfileShowcaseProducts({ handle, cursor? })
Parameters:
- handle (required, string) - TikTok handle whose profile showcase products should be listed.
- cursor (optional, string) - Pagination cursor returned by a previous response.
- region (optional, string) - Optional ISO 3166-1 country code for the request.
Pagination: send query `cursor` from prior `data.page.nextCursor`; stop when `data.page.hasMore` is false.
Empty results: An empty `data.products` array can mean no showcased products, a private profile, or other cases—there is no `lookupStatus` field on this route.
Disambiguation: Call `GET /v1/tiktok/profiles/{handle}` when you need explicit profile lookup status before interpreting an empty showcase list.
curl "https://api.socialfetch.dev/v1/tiktok/profiles/mrtiktokreviews/showcase-products" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/tiktok/ad-library/ads
Get TikTok Ad Library ad
Credit cost: 1 credit per successful request.
Docs: https://www.socialfetch.dev/docs/api/v1/tiktok/ad-library/ads/get.mdx
SDK: client.tiktok.getAdLibraryAd({ adId: "7646829987799334920" })
Parameters:
- adId (optional, string) - TikTok Ad Library or Top Ads ad id.
- url (optional, string) - Public TikTok Ad Library or Top Ads detail URL for the ad.
Outcome field: `data.lookupStatus` in `found`, `not_found`
curl "https://api.socialfetch.dev/v1/tiktok/ad-library/ads?adId=7646829987799334920" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/tiktok/ad-library/ads/search
Search TikTok Ad Library ads
Credit cost: 1 credit per successful request.
Docs: https://www.socialfetch.dev/docs/api/v1/tiktok/ad-library/ads/search/get.mdx
SDK: client.tiktok.searchAdLibraryAds({ query: "spotify", region: "US" })
Parameters:
- region (optional, string, enum: DZ | AR | AU | AT | AZ | BH | BD | BY | BE | BO | BR | BG | KH | CA | CL | CO | CR | HR | CY | CZ | DK | DO | EC | EG | EE | FI | FR | DE | GR | GT | JO | HU | ID | IQ | IE | IL | IT | JP | KZ | KE | KW | LV | LB | MY | MX | MA | NL | NZ | NG | NO | OM | PK | PA | PY | PE | PH | PL | PT | PR | QA | LT | RO | SA | RS | SG | SK | SI | ZA | KR | ES | LK | SE | CH | TW | TH | TR | AE | GB | US | UY | VN) - Country code for Top Ads results. Defaults to US when omitted.
- period (optional, string, enum: 7 | 30 | 180) - Time window in days for Top Ads.
- query (optional, string) - Optional keyword to search ad titles and content.
- advertiserName (optional, string) - Search the public TikTok Ads Library by advertiser name. When set, results come from the public Ads Library instead of Top Ads.
- orderBy (optional, string, enum: for-you | impression | play-2s-rate | play-6s-rate | cvr | ctr | like) - Sort metric for Top Ads. Defaults to for-you when omitted.
- industry (optional, string, enum: apparel-accessories | appliances | apps | baby-kids-maternity | beauty-personal-care | business-services | ecommerce-non-app | education | financial-services | food-beverage | games | health | home-improvement | household-products | life-services | news-entertainment | pets | sports-outdoor | tech-electronics | travel | vehicle-transportation) - Industry filter for Top Ads.
- objective (optional, string, enum: app-installs | conversions | lead-generation | product-sales | reach | traffic | video-views) - Campaign objective filter for Top Ads.
- duration (optional, string, enum: under-10s | 10-20s | 20-30s | 30-40s | 40-50s | over-50s) - Video duration filter for Top Ads.
- likes (optional, string, enum: top-1-20 | top-21-40 | top-41-60 | top-61-80 | top-81-100) - Likes percentile filter for Top Ads.
- adFormat (optional, string, enum: spark-ads | non-spark-ads) - Ad format filter for Top Ads.
- adLanguage (optional, string, enum: en | es | ar | vi | th | de | id | pt | fr | ms | nl | ja | it | ro | zh-Hant | ko) - Ad language filter for Top Ads.
- cursor (optional, string) - Opaque pagination cursor from a previous response.
Pagination: send query `cursor` from prior `data.page.nextCursor`; stop when `data.page.hasMore` is false.
curl "https://api.socialfetch.dev/v1/tiktok/ad-library/ads/search?region=DZ&query=spotify" \
  -H "x-api-key: YOUR_API_KEY"