references/comparison.md
---
name: tiktok-api-comparison
description: How fetcher.sh's TikTok endpoints compare to the official TikTok/Research API and a self-hosted headless-browser scraper, qualitative and scoped to what each actually does.
---
# TikTok data access — comparing your options
Three ways to get TikTok data programmatically. This is a qualitative
comparison of access models, not a pricing sheet — treat any specific
competitor price you see elsewhere as something to verify yourself, not
something repeated here.
## Official TikTok APIs (Display API / Research API)
- Requires a developer account and app review; the Research API additionally
requires proof of academic or nonprofit research status for most endpoints.
- Access is scoped and permissioned per use case — general commercial scraping
(arbitrary keyword search, arbitrary profile lookup) isn't the primary
target audience the way it is for ad-hoc data pulls.
- Best fit when you're an approved research institution or a product with an
official partnership needing guaranteed, ToS-sanctioned access.
## Headless-browser scraper (self-hosted)
- No API key at all — you drive a real browser (Playwright/Puppeteer) against
tiktok.com and parse the DOM or intercepted XHR responses yourself.
- You own and pay for the infrastructure (proxies, browser fleet, CAPTCHA/
device-fingerprint handling) and the maintenance burden when TikTok changes
its frontend or signing scheme.
- No fixed per-call price — cost is your compute + proxy bill, which scales
with volume and gets more expensive as anti-bot defenses tighten.
- Best fit when you need something the same subdomain-per-service model
doesn't expose yet, or you're already running scraping infra for other
sites and want one more target.
## fetcher.sh (`tiktok.fetcher.sh`)
- No developer account, no OAuth, no app review — authenticate to
`tiktok.fetcher.sh` itself with a Bearer key or an x402 payment.
- Flat $0.004/call across all 13 endpoints (see
[`endpoints.md`](endpoints.md)), no monthly minimum, no tier to outgrow.
- Fixed endpoint set (search, profiles, posts, followers, hashtags, sounds,
locations) mirrored across 11 services with the same JSON envelope and the
same MCP tool names — one integration pattern reused everywhere.
- Read-only, on-demand: no webhooks, no streaming, no writes/posting. If you
need "notify me when X happens," you poll on a schedule yourself.
- Best fit when you want ad-hoc or moderate-volume reads without upfront
account setup or research-status paperwork, and you're fine treating TikTok
as one of several data sources behind the same MCP/REST pattern.
## Named providers to benchmark against
Don't take any provider's framing (including this one) at face value — pull
the same data from each and compare the actual response. A few concrete
starting points, current as of this writing (verify pricing and limits
yourself before deciding, since all three change their terms independently
of this repo):
| Provider | Docs | What to check |
| --- | --- | --- |
| TikTok for Developers (Display/Research API) | [developers.tiktok.com](https://developers.tiktok.com/) | Do you actually qualify for the access tier your use case needs? |
| Apify TikTok Scraper | [apify.com/clockworks/tiktok-scraper](https://apify.com/clockworks/tiktok-scraper) | Does an Actor-based, dataset/export-oriented workflow fit your pipeline better than direct REST? |
| Bright Data TikTok Scraper API | [docs.brightdata.com/datasets/scrapers/tiktok/introduction](https://docs.brightdata.com/datasets/scrapers/tiktok/introduction) | Do you need bulk async collection (1000s of URLs) more than single-call reads? |
## Build your own comparison
Pick one fixed test — the same profile, the same search keyword, the same
video ID — and run it against fetcher.sh and whichever provider above is a
candidate. Record, per provider:
- Which required fields actually came back (not just which fields the docs
promise)
- Cost for the exact rows you kept, after discarding anything you didn't need
- Time from request to usable JSON
- What happens on the second and third call — does pagination stay stable,
does a cached/rate-limited path kick in, does the price change
A five-minute test like this is worth more than any comparison table,
including this one.
## Quick decision guide
| Need | Pick |
| --- | --- |
| Approved academic/nonprofit research with official data access | Official Research API |
| One-off script, no account setup, pay only for what you call | fetcher.sh |
| Already running scraping infra, need something fetcher.sh doesn't expose | Headless browser |
| Same integration pattern across TikTok, X, Instagram, Reddit, etc. | fetcher.sh |
## See also
- [`endpoints.md`](endpoints.md) — full parameter reference
- [`scenarios.md`](scenarios.md) — worked `curl` examples
- [`faq.md`](faq.md) — task-oriented "how do I..." answers
references/endpoints.md
---
name: tiktok-api-endpoints
description: Full parameter reference for every TikTok endpoint on tiktok.fetcher.sh — path params, query params, required flags, and enum values, straight from the live OpenAPI contract.
---
# TikTok — full endpoint reference
Base URL: `https://tiktok.fetcher.sh`. All 13 endpoints are `GET`,
authenticated with either `Authorization: Bearer bby_live_...` (credits) or
an x402 payment — see [`SKILL.md`](../SKILL.md) for the payment flow. Path
parameters are written as `{param}`; substitute the real value. `?` marks an
optional query param. Every endpoint on this host is a flat $0.004/call.
This file lists every parameter that exists. It does not describe response
fields — the response shape is generated at request time from the live
handlers, so the authoritative machine-readable version is always
[`/openapi.json`](https://tiktok.fetcher.sh/openapi.json). Treat any field
name you haven't seen in an actual response as unverified.
## Search
| Endpoint | Params |
| --- | --- |
| `/api/post/search` | `keyword` (required) · `cursor`? · `region`? · `sortType`? (`RELEVANCE`, `MOST_LIKED`, `DATE_POSTED`) · `dateRange`? (`ALL_TIME`, `YESTERDAY`, `THIS_WEEK`, `THIS_MONTH`, `LAST_THREE_MONTHS`, `LAST_SIX_MONTHS`) |
This is the hero endpoint — `sortType=MOST_LIKED` plus a `dateRange` is the
combination for a "what's viral" query; leave both unset for TikTok's default
relevance ranking.
## Profiles
| Endpoint | Params |
| --- | --- |
| `/api/user/handle/{username}` | none |
Returns the numeric user ID needed by every `/api/user/{id}/...` endpoint
below.
## Users
| Endpoint | Params |
| --- | --- |
| `/api/user/{id}/posts` | `region`? · `cursor`? |
| `/api/user/{id}/followers` | `cursor`? |
| `/api/user/{id}/followings` | `cursor`? |
`{id}` is the numeric ID from the handle lookup, not the `@username`.
## Posts
| Endpoint | Params |
| --- | --- |
| `/api/post` | `url` (required) |
| `/api/post/{id}` | `region`? |
| `/api/post/{id}/comments` | `cursor`? |
| `/api/post/{id}/comments/{commentId}/replies` | `cursor`? |
`/api/post` takes a full TikTok video URL directly — useful when you have a
link but not the numeric video ID. `/api/post/{id}` needs just the ID (the
number in the URL). `{commentId}` for replies comes from a comment object
returned by `/api/post/{id}/comments`.
## Hashtags, sounds, and locations
| Endpoint | Params |
| --- | --- |
| `/api/hashtag/handle/{name}` | none |
| `/api/hashtag/{id}/posts` | `region`? · `cursor`? |
| `/api/music/{id}/posts` | `region`? · `cursor`? |
| `/api/location/{locationId}/posts` | `cursor`? · `region`? |
`/api/hashtag/handle/{name}` resolves a hashtag name (no `#`) to the numeric
ID needed by `/api/hashtag/{id}/posts`. `region` on any endpoint is a 2-letter
country code (e.g. `US`) and filters/localizes results where TikTok supports
it — it's optional everywhere it appears.
## See also
- [`scenarios.md`](scenarios.md) — one worked `curl` per endpoint
- [`faq.md`](faq.md) — task-oriented "how do I..." answers
- [`comparison.md`](comparison.md) — fetcher.sh vs. the official TikTok API vs. a browser scraper
references/faq.md
---
name: tiktok-api-faq
description: Frequently asked questions about the TikTok API on fetcher.sh — viral search, followers, monitoring, and rate limits, answered with exact endpoints.
---
# TikTok API alternative — FAQ
## Getting started
### Do I need a TikTok developer account or app review?
No. `tiktok.fetcher.sh` is a separate read-only proxy — you authenticate to
*it*, not to TikTok. No developer account, no app review.
### What payment methods are supported?
Prepaid credits (`Authorization: Bearer bby_live_...`) or x402 micropayments
in USDC on Base, Polygon, Arbitrum, Monad, or Solana — see the [`fetcher`
skill](../../fetcher/SKILL.md) for setup.
### Is there a rate limit?
No fixed per-minute cap enforced by fetcher.sh itself — cost is the limiter:
each call is billed individually (credits or x402), so throughput is bounded
by your budget and by the upstream page latency, not by a quota.
## Search and discovery
### How do I find viral or trending posts for a keyword?
`GET /api/post/search?keyword=...&sortType=MOST_LIKED&dateRange=THIS_WEEK`
(or `THIS_MONTH`) on `tiktok.fetcher.sh`. See
[`scenarios.md`](scenarios.md).
### Can I filter search by video duration or resolution?
No — `/api/post/search` only exposes `sortType`, `dateRange`, and `region`.
There's no duration or resolution filter on this host; you'd have to filter
client-side using fields returned in the response.
### How do I look up a post if I only have the TikTok link, not the ID?
`GET /api/post?url=<the full tiktok.com URL>` — no need to parse the video ID
out of the URL yourself.
### How do I find all posts using a specific sound?
`GET /api/music/{id}/posts`, where `{id}` is the sound's numeric ID (visible
in the sound's TikTok URL).
## Profiles and followers
### How do I get a creator's follower list?
`GET /api/user/{id}/followers`, where `{id}` is the numeric ID from
`GET /api/user/handle/{username}`. Paginate with the returned `cursor` until
the response stops returning one.
### Can I export followers to CSV directly?
Not server-side. Fetcher.sh returns JSON; paginate through
`/api/user/{id}/followers` and write the pages to a CSV yourself. There's no
built-in export job.
### Can I get a user's liked posts?
No — there's no liked-posts endpoint on this host, only `/api/user/{id}/posts`
(what they posted). TikTok itself also hides most accounts' likes tab by
default, which is part of why it isn't exposed here.
## Comments
### How do I get comments on a video, including replies?
`GET /api/post/{id}/comments` for top-level comments, then
`GET /api/post/{id}/comments/{commentId}/replies` for the replies under a
specific comment.
## Monitoring and regional scope
### How do I monitor a hashtag for new posts?
There's no webhook or streaming endpoint. Poll `/api/hashtag/{id}/posts` (or
`/api/post/search` with `sortType=DATE_POSTED`) on a schedule and diff
against the post IDs you've already seen.
### Does `region` filter results to one country?
Where it's accepted (search, hashtag/music/location posts, user posts),
`region` is a 2-letter country code that scopes/localizes the underlying
TikTok request — it's optional everywhere it appears, not required.
## Discovery and reference
### Can an agent discover these endpoints without reading this file?
Yes — `tiktok.fetcher.sh/mcp` exposes `search_endpoints`, `describe_endpoint`,
and `fetch_data` as MCP tools, so an MCP-connected agent can explore the API
live instead of relying on this document.
### Where's the authoritative schema if this doc goes stale?
`https://tiktok.fetcher.sh/openapi.json` and `https://tiktok.fetcher.sh/llms.txt`
are generated from the live route handlers and always match production.
## See also
- [`endpoints.md`](endpoints.md) — full parameter reference
- [`scenarios.md`](scenarios.md) — worked `curl` examples
- [`comparison.md`](comparison.md) — fetcher.sh vs. the official TikTok API vs. a browser scraper
references/scenarios.md
---
name: tiktok-api-scenarios
description: Worked curl examples for every TikTok endpoint on tiktok.fetcher.sh, one per endpoint, including pagination.
---
# TikTok — full scenario cookbook
Every call below assumes:
```bash
export FETCHER_API_KEY="bby_live_xxxxxxxxxxxx"
```
Swap the `curl -H "Authorization: Bearer $FETCHER_API_KEY"` prefix for a bare
`curl` if you're paying per call with x402 instead — see the [`fetcher`
skill](../../fetcher/SKILL.md).
## Search
**Keyword search, default relevance ranking:**
```bash
curl -H "Authorization: Bearer $FETCHER_API_KEY" \
--data-urlencode "keyword=matcha latte" -G \
"https://tiktok.fetcher.sh/api/post/search"
```
**Most-liked posts this month:**
```bash
curl -H "Authorization: Bearer $FETCHER_API_KEY" \
--data-urlencode "keyword=ai agents" -G \
--data-urlencode "sortType=MOST_LIKED" \
--data-urlencode "dateRange=THIS_MONTH" \
"https://tiktok.fetcher.sh/api/post/search"
```
**Region-scoped search with pagination:**
```bash
curl -H "Authorization: Bearer $FETCHER_API_KEY" \
--data-urlencode "keyword=streetwear" -G \
--data-urlencode "region=US" \
--data-urlencode "cursor=<cursor from previous response>" \
"https://tiktok.fetcher.sh/api/post/search"
```
## Profiles
**Resolve a profile by handle:**
```bash
curl -H "Authorization: Bearer $FETCHER_API_KEY" \
"https://tiktok.fetcher.sh/api/user/handle/khaby.lame"
```
## Users
**A user's posts:**
```bash
curl -H "Authorization: Bearer $FETCHER_API_KEY" \
"https://tiktok.fetcher.sh/api/user/6820094808943265798/posts"
```
**A user's followers, paginated:**
```bash
curl -H "Authorization: Bearer $FETCHER_API_KEY" \
"https://tiktok.fetcher.sh/api/user/6820094808943265798/followers"
# next page
curl -H "Authorization: Bearer $FETCHER_API_KEY" \
--data-urlencode "cursor=<cursor from previous response>" -G \
"https://tiktok.fetcher.sh/api/user/6820094808943265798/followers"
```
**Accounts a user follows:**
```bash
curl -H "Authorization: Bearer $FETCHER_API_KEY" \
"https://tiktok.fetcher.sh/api/user/6820094808943265798/followings"
```
## Posts
**Look up a post by URL (no need to extract the ID yourself):**
```bash
curl -H "Authorization: Bearer $FETCHER_API_KEY" \
--data-urlencode "url=https://www.tiktok.com/@khaby.lame/video/7137423965982686469" -G \
"https://tiktok.fetcher.sh/api/post"
```
**Look up a post by numeric ID:**
```bash
curl -H "Authorization: Bearer $FETCHER_API_KEY" \
"https://tiktok.fetcher.sh/api/post/7137423965982686469"
```
**A post's comments:**
```bash
curl -H "Authorization: Bearer $FETCHER_API_KEY" \
"https://tiktok.fetcher.sh/api/post/7137423965982686469/comments"
```
**Replies to a specific comment:**
```bash
curl -H "Authorization: Bearer $FETCHER_API_KEY" \
"https://tiktok.fetcher.sh/api/post/7137423965982686469/comments/<commentId>/replies"
```
## Hashtags, sounds, and locations
**Resolve a hashtag to its numeric ID:**
```bash
curl -H "Authorization: Bearer $FETCHER_API_KEY" \
"https://tiktok.fetcher.sh/api/hashtag/handle/fyp"
```
**Posts under a hashtag:**
```bash
curl -H "Authorization: Bearer $FETCHER_API_KEY" \
"https://tiktok.fetcher.sh/api/hashtag/<hashtagId>/posts"
```
**Posts using a specific sound:**
```bash
curl -H "Authorization: Bearer $FETCHER_API_KEY" \
"https://tiktok.fetcher.sh/api/music/<musicId>/posts"
```
**Posts tagged at a location:**
```bash
curl -H "Authorization: Bearer $FETCHER_API_KEY" \
"https://tiktok.fetcher.sh/api/location/<locationId>/posts"
```
## See also
- [`endpoints.md`](endpoints.md) — full parameter reference
- [`faq.md`](faq.md) — task-oriented "how do I..." answers
- [`comparison.md`](comparison.md) — fetcher.sh vs. the official TikTok API vs. a browser scraper
SKILL.md
---
name: tiktok-api
description: >-
A TikTok API alternative on fetcher.sh — pay-per-call in USDC via x402, or
prepaid credits with a Bearer key, no login and no app review. Use when the
user wants to search TikTok posts by keyword and sort by most-liked or most
recent within a date range, look up a post by its share URL or ID, scrape a
TikTok profile by @username, pull a user's posts, followers, or followings,
fetch a hashtag's posts, pull posts using a specific sound/music track, get
posts from a location, or read a post's comments and comment replies. Also
covers TikTok trend tracking, hashtag monitoring, influencer discovery,
competitor content analysis, and TikTok data pipelines without official
TikTok API access or a scraping browser.
keywords:
- tiktok
- tiktok-api
- tiktok-api-alternative
- tiktok-data
- social-media
- social-listening
- hashtag-tracking
- x402
- ai-agent
---
# TikTok API
TikTok data on demand: keyword post search with sort/date filters, profile
lookup by handle, followers and followings, hashtag and music/sound feeds,
location-based posts, and comment threads — one plain HTTP GET per call, paid
as you go. No login, no session cookies, no browser automation, no TikTok
developer app review.
Base URL: `https://tiktok.fetcher.sh`
## Quick reference
| | |
| --- | --- |
| Base URL | `https://tiktok.fetcher.sh` |
| Auth | `Authorization: Bearer bby_live_...` or x402 (USDC) |
| Price | $0.004/call (flat) |
| Endpoints | 13, all `GET` |
| MCP | `https://tiktok.fetcher.sh/mcp` |
| Machine-readable | `/openapi.json` · `/llms.txt` · `/skill.md` |
## Which endpoint do I need?
| I want to... | Call |
| --- | --- |
| Search posts by keyword (optionally most-liked/recent) | `GET /api/post/search` |
| Look up a post by its share URL | `GET /api/post?url=...` |
| Look up a profile by @username | `GET /api/user/handle/{username}` |
| Get a user's posts, followers, or followings | `GET /api/user/{id}/posts` / `/followers` / `/followings` |
| Get a post's comments | `GET /api/post/{id}/comments` |
| Find posts under a hashtag | `GET /api/hashtag/{id}/posts` |
| Find posts using a specific sound | `GET /api/music/{id}/posts` |
Full param details for every row: [`references/endpoints.md`](references/endpoints.md).
## Authentication
Two ways to pay, same data — full mechanics in the [`fetcher`
skill](../fetcher/SKILL.md):
```bash
# 1. Prepaid credits (recommended — get a key at https://fetcher.sh/topup
# or via POST /api/credits/topup, see the fetcher skill)
export FETCHER_API_KEY="bby_live_xxxxxxxxxxxx"
curl -H "Authorization: Bearer $FETCHER_API_KEY" \
"https://tiktok.fetcher.sh/api/post/search?keyword=hello"
# 2. x402 pay-per-call — omit the header; a GET with no payment returns 402
# with machine-readable payment requirements (USDC on Base, Polygon,
# Arbitrum, Monad, or Solana). @x402/fetch signs and retries automatically.
```
Every response is `{ "status": number, "message": string, "data": ... }`; the
HTTP status mirrors `status`.
## Endpoints (13 — all GET, $0.004/call)
| Endpoint | What it returns |
| --- | --- |
| `/api/post/search` | Posts matching a keyword; sort and date-range filters |
| `/api/post` | A single post resolved from its share URL |
| `/api/post/{id}` | A single post by ID |
| `/api/post/{id}/comments` | A post's comments |
| `/api/post/{id}/comments/{commentId}/replies` | Replies to a comment |
| `/api/user/handle/{username}` | Profile by @username |
| `/api/user/{id}/posts` | A user's posts |
| `/api/user/{id}/followers` | A user's followers |
| `/api/user/{id}/followings` | Accounts a user follows |
| `/api/hashtag/handle/{name}` | Hashtag metadata by name |
| `/api/hashtag/{id}/posts` | Posts under a hashtag |
| `/api/music/{id}/posts` | Posts using a sound/music track |
| `/api/location/{locationId}/posts` | Posts tagged at a location |
`{id}` / `{username}` / `{name}` are path parameters. Optional query params
(`cursor`, `region`) paginate or geo-scope results; `keyword` (search) and
`url` (post lookup) are required where they appear.
## Scenarios
**Most liked posts this month:**
```bash
curl -H "Authorization: Bearer $FETCHER_API_KEY" \
--data-urlencode "keyword=ai agent" -G \
--data-urlencode "sortType=MOST_LIKED" \
--data-urlencode "dateRange=THIS_MONTH" \
"https://tiktok.fetcher.sh/api/post/search"
```
**Posted yesterday, most recent first:**
```bash
curl -H "Authorization: Bearer $FETCHER_API_KEY" \
--data-urlencode "keyword=crypto payments" -G \
--data-urlencode "sortType=DATE_POSTED" \
--data-urlencode "dateRange=YESTERDAY" \
"https://tiktok.fetcher.sh/api/post/search"
```
Other `sortType` values: `RELEVANCE`. Other `dateRange` values: `ALL_TIME`,
`THIS_WEEK`, `LAST_THREE_MONTHS`, `LAST_SIX_MONTHS`.
**Look up a post by its share URL, or directly by ID:**
```bash
curl -H "Authorization: Bearer $FETCHER_API_KEY" -G \
--data-urlencode "url=https://www.tiktok.com/@username/video/1234567890123456789" \
"https://tiktok.fetcher.sh/api/post"
curl -H "Authorization: Bearer $FETCHER_API_KEY" \
"https://tiktok.fetcher.sh/api/post/1234567890123456789"
```
**A post's comments and comment replies:**
```bash
curl -H "Authorization: Bearer $FETCHER_API_KEY" \
"https://tiktok.fetcher.sh/api/post/1234567890123456789/comments"
curl -H "Authorization: Bearer $FETCHER_API_KEY" \
"https://tiktok.fetcher.sh/api/post/1234567890123456789/comments/9876543210/replies"
```
**A profile by @handle, then its posts, followers, and followings:**
```bash
curl -H "Authorization: Bearer $FETCHER_API_KEY" \
"https://tiktok.fetcher.sh/api/user/handle/khaby.lame"
curl -H "Authorization: Bearer $FETCHER_API_KEY" \
"https://tiktok.fetcher.sh/api/user/6935741396776976390/posts"
curl -H "Authorization: Bearer $FETCHER_API_KEY" \
"https://tiktok.fetcher.sh/api/user/6935741396776976390/followers"
```
**A hashtag's metadata, then its posts:**
```bash
curl -H "Authorization: Bearer $FETCHER_API_KEY" \
"https://tiktok.fetcher.sh/api/hashtag/handle/fyp"
curl -H "Authorization: Bearer $FETCHER_API_KEY" \
"https://tiktok.fetcher.sh/api/hashtag/1234567890/posts"
```
**Posts using a specific sound, and posts from a location:**
```bash
curl -H "Authorization: Bearer $FETCHER_API_KEY" \
"https://tiktok.fetcher.sh/api/music/1234567890123456789/posts"
curl -H "Authorization: Bearer $FETCHER_API_KEY" \
"https://tiktok.fetcher.sh/api/location/1234567890123456789/posts"
```
## MCP
```json
{
"mcpServers": {
"tiktok": {
"url": "https://tiktok.fetcher.sh/mcp",
"headers": { "Authorization": "Bearer bby_live_..." }
}
}
}
```
Free: `search_endpoints`, `describe_endpoint`, `check_balance`. Paid:
`fetch_data` (any endpoint above), `topup_credits`, plus the named shortcut
`tiktok_post_search`. Drop the `headers` block to pay per call with x402
instead — see the [`fetcher` skill](../fetcher/SKILL.md) for the full flow.
## Errors
- `400` — missing/invalid parameter (message names it)
- `401` — unknown or rotated key
- `402` — payment required (x402 challenge) or `topup_required` (credits
exhausted)
- `404` — not a priced path
- No rate limits; no refunds on upstream failures (settlement precedes
delivery)
## Reference
- Deep dives: [`references/endpoints.md`](references/endpoints.md) (every
param) · [`references/scenarios.md`](references/scenarios.md) (one `curl`
per endpoint) · [`references/faq.md`](references/faq.md) ·
[`references/comparison.md`](references/comparison.md) (vs. the official
TikTok API and a browser scraper)
- Task guides: [viral post search](../../task-guides/tiktok-viral-post-search.md) ·
[profile and followers](../../task-guides/tiktok-profile-and-followers.md)
- Slash command: [`/tiktok-search`](../../commands/tiktok-search.md)
- Full agent setup: <https://tiktok.fetcher.sh/skill.md>
- OpenAPI 3.1 contract: <https://tiktok.fetcher.sh/openapi.json>
- Condensed catalog: <https://tiktok.fetcher.sh/llms.txt>
- Payment, credits, and MCP deep dive: [`fetcher` skill](../fetcher/SKILL.md)
- Site: <https://tiktok.fetcher.sh>