Start with a public TikTok handle, read its profile metrics, then save a page of videos as rows. This guide uses charlidamelio, a public figure, and the Social Fetch TikTok API. You can replace the handle with a public account relevant to your work.
To check a single account or video without code, use the free TikTok profile viewer or TikTok transcript generator.
You need a Social Fetch account with credits. The Playground lets you try a request without writing code. For your own script, create an API key and keep it on your server. The quickstart explains that setup.
DIY browser scraping on TikTok
A browser scraper opens TikTok pages and extracts the data it can see. That workflow must handle changes to page structure, loading behaviour and verification screens. The public profile below shows rounded totals, while the API response later in this guide provides numeric counts you can save and compare.
If you choose to maintain a browser scraper, detect verification and unavailable pages explicitly. Do not interpret a missing element as a zero follower count. See Social Fetch vs DIY scraping for the maintenance trade-offs.
TikTok official APIs
TikTok's Display API reads profile information and video metadata for a user who authorises your app. It requires an approved app, scopes and a user access token. It is useful when your users connect their own accounts.
TikTok's Research Tools cover public account and video data for eligible researchers with an approved project. Their eligibility rules require research independent of commercial interests. Check those requirements before choosing them for a project.
The following Social Fetch requests take a public handle and use your Social Fetch key. They do not ask the TikTok account owner to authorise your app.
Get a profile in the Playground
- Open the Playground profile request.
- Check that the endpoint is Get TikTok profile and set handle to
charlidamelio. Use the username, rather than the display name. - Click Send, then read the Response tab. This makes a real request and spends credits.
For the same request from a shell, set SOCIALFETCH_API_KEY to your own key, then run:
Read data.lookupStatus first. When it is found, data.profile contains details such as the handle and display name, and data.metrics contains profile totals. Both objects are nullable, so check them before accessing fields. The profile reference lists the full response.
List a profile's videos
- Open the Playground videos request.
- Check handle, set sortBy to
latest, and leave cursor empty for the first page. - Click Send. Read
data.videosfor the rows anddata.pagefor the next-page information.
When data.page.hasMore is true and data.page.nextCursor is present, send that value as cursor on the next request. Keep the handle, sort order and other options the same. Each page is a separate billed request.
Pinned videos are included by default. If you use includePinned=false, some pages can be shorter or empty after filtering. Keep following the page information even when a found page has no videos. See the profile videos reference for the available options.
Save pages with the TypeScript SDK
This program saves up to two pages to tiktok-videos.jsonl, one JSON object per line. The page limit is a spending budget, not a promise to retrieve the whole account. It stops on unavailable accounts, missing continuation data or a repeated cursor, and removes duplicate video IDs across pages.
Install the SDK and a TypeScript runner:
Save this as scrape-tiktok.mts. The .mts extension makes it an ES module, which the SDK requires, even in a CommonJS project. Set SOCIALFETCH_API_KEY in your environment, then run npx tsx scrape-tiktok.mts.
The SDK returns a Result: check result.ok before reading result.value. A failed request can still leave useful rows from earlier successful pages, so the program writes the rows it has collected. Save each page as it arrives if you need recovery after a process crash.
Reading the response
data.metrics.followers is a profile total. data.videos[i].stats.views, likes, comments, shares and saves describe an individual video. Video captions and creation dates can be null. Preserve nulls rather than replacing them with invented text or dates.
Record when you collect each snapshot. A page of recent videos is a sample, and its average performance does not describe every video the account has posted. Metrics can change between requests. Media URLs can expire; use the video URL or ID as a reference rather than assuming a download link lasts indefinitely.
Costs and unavailable accounts
A completed profile lookup costs 1 credit. A completed profile videos request costs 1 credit without hosted media. This includes private and not_found outcomes. The two-page SDK program therefore spends up to 2 credits on completed requests with the shown options. hostMedia=true has additional storage charges; this guide leaves it off. Check meta.creditsCharged for the actual charge and meta.requestId when asking support about a request.
For videos, private and not_found come with an empty list. A found response can also have an empty list, so do not use list length alone to decide whether an account exists.
Common questions
Do I need a TikTok account?
These examples need a Social Fetch account and key. They do not require TikTok sign-in. They cannot unlock private videos, direct messages or account-owner analytics. Check the terms and permissions that apply to your collection and use of data.
Can I search or get transcripts too?
Use TikTok search to find videos by query. To work with spoken text, follow the TikTok transcript guide. Those endpoints have their own inputs and response shapes; do not assume they return the profile envelope above.
Why did my request fail?
bad_request means you should check your handle and query parameters against the endpoint reference. unauthorized means you should check the key. For insufficient_credits, check the workspace balance; a key spending limit has its own refusal and is not fixed by adding workspace credits. For temporarily_unavailable, follow Retry-After when present and keep retries bounded. See Errors and send the request ID when you contact support.