TikTok Profile Scraper API
Turn any public TikTok profile into structured JSON. Filter by date and engagement while the scrape runs, then page through results by cursor or download the whole thing as one signed file.
- What is the TikTok Profile Scraper API?
- The TikTok Profile Scraper API is an asynchronous REST endpoint that returns public video metadata for a TikTok profile. You POST a profile URL with optional date and likes filters, receive a task id immediately, then page through matching videos by cursor or download the full scrape as one signed JSON file.
Why the TikTok Profile Scraper API?
Most TikTok scrapers download an entire profile and leave the filtering to you. This one pushes your filters into the scrape itself. Because TikTok serves profile videos newest-first, an after_datetime boundary lets the scraper stop fetching pages the moment it crosses your date, which is the difference between reading 41 pages and reading 530.
- Filter Before You Pay — Date and likes filters run server-side during the scrape, and an
after_datetimeboundary stops pagination outright instead of downloading a whole profile and discarding most of it. - Async by Design — A single
POSTreturns 202 with a task id in milliseconds, so a five-minute scrape of a 5,000-post profile never sits inside an HTTP request that a proxy can time out. - Two Delivery Paths — Cursor pagination for incremental consumption, plus a signed one-file JSON download for bulk import and ETL. Both are always available on a completed task.
- Per-Page Billing With Automatic Reversal — You pay 1 credit per 10,000 TikTok pages read. Any failure — private profile, provider error, server fault — reverses every charged page and withholds the result.
- Engagement Metrics Included — Every video carries views, likes, reposts, comments, duration, sound track, and a UTC
published_at, not just an id and a URL.
How It Works
Sign up and generate an API key in VidNavigator Studio. TikTok profile scraping is gated by its own permission, so the key needs TikTok Profile access enabled.
POST a TikTok profile URL such as https://www.tiktok.com/@tiktok to /v1/tiktok/profile, with optional max_posts, after_datetime, before_datetime, min_likes, and max_likes. Single video URLs are rejected.
The endpoint returns 202 Accepted with a task id and a check_status_url. Poll that URL until task_status flips from processing to completed or failed. Polling never consumes credits.
Walk the cursor for incremental pages of up to 500 videos each, or follow the signed download_url to pull the entire scrape as one JSON file with no auth header required.
What You Can Filter
| Parameter | Behavior |
|---|---|
| profile_url | Required. A TikTok profile URL like https://www.tiktok.com/@username. Single video URLs are rejected with 400. |
| max_posts | Maximum matching videos to return. Scraping stops once reached. Hard cap: 5,000. |
| after_datetime | Inclusive lower bound, as YYYY-MM-DD or a timezone-aware ISO datetime. Stops the scrape once older videos are reached, so it reduces cost as well as result size. |
| before_datetime | Inclusive upper bound, same accepted formats. Newer videos are skipped without stopping pagination. |
| min_likes / max_likes | Keep only videos whose like count falls within the range. Applied per video as the scraper iterates. |
Date filters accept either YYYY-MM-DD or a timezone-aware ISO datetime such as 2026-01-01T00:00:00Z. Filtering uses each video's UTC timestamp when TikTok provides one, and falls back to the upload date when it does not.
Built for Modern Workflows
Creator Vetting & Influencer Discovery
Pull a creator’s last 90 days of posts with min_likes set to your engagement floor, and get a per-video view, like, repost, and comment history instead of a follower count. One scrape is enough to tell a consistent performer from a single viral fluke.
Competitive Content Monitoring
Run a nightly scrape of each competitor profile bounded by after_datetime to yesterday. Because the boundary stops pagination, an incremental daily delta costs a handful of pages rather than a full profile re-read.
Dataset Building for Research & ML
Collect up to 5,000 videos per profile with titles, descriptions, sound tracks, durations, and engagement counts, then take the signed download_url straight into a warehouse load or a training-data pipeline.
Quickstart
Submit a profile URL, poll the task id, then read the result. The Python example below covers all three steps, including walking the cursor to the end of the result set.
Results are scoped to the API key that created them. Requesting another account's task id returns 404, never someone else's data.
- POST /v1/tiktok/profile — submit a scrape
- GET /v1/tiktok/profile/{task_id} — poll, paginate, and get the download URL
- POST /v1/transcript — captions for any result, when they exist
- POST /v1/transcribe — speech-to-text when they do not
- POST /v1/extract/video — typed columns against your own schema
Read a Whole TikTok Account, Not Just Its Metadata
Metadata tells you which posts worked. It does not tell you why. Because every scraped video carries a url, you can feed it straight into transcription — so one script turns an entire account into engagement figures plus the words that produced them. This is the pattern most teams actually want, and with the SDK it is about 30 lines.
Or skip the transcript and go straight to a table
If you know what you are looking for, swap get_transcript for extract_video_data and hand it a schema. You get one row per video instead of a wall of text — ready for a warehouse, a spreadsheet, or a dashboard.
Competitor teardown
Which hooks, formats, and offers correlate with their top-performing posts — measured across their whole catalogue, not the three videos you happened to watch.
Creator vetting
Before you pay for a partnership, read every brand mention and claim the creator has made on camera in the last 90 days.
Searchable archive
Transcribe an account once, embed the text, and every future question about what was said becomes a query instead of a re-scrape.
Transcription is billed separately from scraping — the scrape pays for TikTok pages, the transcript pays per video (or per hour of speech-to-text when a video has no captions). For large accounts, process videos sequentially or with a small concurrency limit. Full reference: GET /v1/transcript and POST /v1/extract/video.
Example Responses
The submit call always returns 202 Accepted. The completed task carries the profile, the matching videos with full engagement metrics, scrape statistics, cursor pagination, and a signed download URL.
Two Ways to Collect Large Results
Cursor Pagination
GET /v1/tiktok/profile/{task_id}?cursor=&limit= returns up to 500 videos per page. The cursor encodes an absolute offset into the completed snapshot, so it stays correct even if you change limit between requests.
Best for incremental consumption, streaming into a queue, or UIs that render results as they arrive.
Signed JSON Download
Every completed task exposes a download_url — a signed link to the whole scrape as one JSON file, valid for about 60 minutes and re-mintable for free.
No auth header is needed, so it works from a browser, a no-code step in Zapier or n8n, or plain curl. Best for bulk import, ETL, and archiving.
Pricing
A profile scrape is billed per TikTok page fetched, as standard requests. With VidNavigator, 1 credit = 10,000 standard requests.
- 1 TikTok page = 1 standard request. A profile page holds roughly 15 videos.
- Worked example: scanning 612 videos consumes 41 pages, or about 0.0041 credits.
- One page is charged up front as a credit gate, so a request with no credits fails fast with
402before any scraping starts. - The rest is reconciled after the scrape, and any failure reverses every charged page and withholds the result.
- Polling and re-minting download URLs are free. Only pages actually read from TikTok are billed.
Because after_datetime stops pagination early, narrowing the window is the most effective way to control cost on large profiles.
Limits and Behavior Worth Knowing
| Behavior | Detail |
|---|---|
| Max videos per scrape | 5,000 (hard cap on max_posts) |
| Max page size | 500 videos per cursor page |
| Task retention | 1 hour from creation, then expired automatically |
| Download URL lifetime | About 60 minutes; re-mint for free by calling GET again |
| Private or empty profile | Task marked failed with an error message; charges reversed |
| Cross-account access | Tasks are scoped to their owner; another key's task id returns 404 |