TikTok Data Scraper — TKLens Technical Docs

Contents

What does TKLens do?
What data can you get from TikTok?
How to scrape TikTok with TKLens?
Input parameters
Output format
Deep analysis report (exclusive)
Pricing
Error codes
Architecture
API & MCP integration
FAQ

1. What does TKLens do?

TKLens extracts public data from TikTok and exports it in your preferred format. Use it for your own data projects, business reports, or as the foundation for new apps.

Extract all videos from any user profile: captions, plays, likes, comments, shares, saves, music, hashtags, publish dates
Account profile: follower/following counts, total likes, bio, verification status
Platform-verified fields: isAd (sponsored or not), location created, text language
Export in JSON, CSV, Excel, or HTML
Exclusive: deep analysis report — viral attribution, paid-traffic detection, hashtag/music stats, posting cadence, risk signals (a layer certain data platforms do not offer)
Connect TKLens to any AI chatbot via MCP server

2. What data can you get from TikTok?

Field	Description
Username / nickname / ID	authorMeta.name, nickName, id
Bio	signature, with bio link
Followers / following	fans, following
Total likes	heart
Plays	playCount (per video)
Likes / Comments / Shares	diggCount, commentCount, shareCount
Caption	text (full caption)
Hashtags	hashtags (platform structured + regex completion)
Music	musicMeta: title, author, original or not, play URL
Publish time	createTime / createTimeISO
Video URL	webVideoUrl
Is ad	isAd (platform-flagged, not inferred)
Location created	locationCreated (country code)
Text language	textLanguage
Pinned	isPinned
Direct video URL	playAddr (downloadable)

3. How to scrape TikTok with TKLens?

Sign up: free with email (free during beta)
Submit: enter any TikTok username in the console, e.g. @princessbridediamonds
Wait: all public videos are collected in the background (usually a few hours, up to 24h for large accounts)
Read the report: 9-section deep analysis, Top10 inline
Download: full CSVs (video details / captions / hashtags / music)

4. Input parameters

Parameter	Type	Default	Description
`handle`	string	required	TikTok username
`max_videos`	integer	40	Max videos; null = all (MCP/API)

5. Output format

Example JSON per video:

{
  "id": "7697441806480461070",
  "text": "How well do you know your girl? #ring #engagementring",
  "textLanguage": "en",
  "createTimeISO": "2025-08-28T17:44:35.000Z",
  "isAd": false,
  "locationCreated": "US",
  "authorMeta": {"name": "princessbridediamonds", "fans": 349600, "heart": 31800000},
  "musicMeta": {"musicName": "original sound", "musicAuthor": "princessbridediamonds"},
  "playCount": 8900000, "diggCount": 23400, "commentCount": 46,
  "shareCount": 145, "collectCount": 1637,
  "webVideoUrl": "https://www.tiktok.com/@princessbridediamonds/video/7697441806480461070"
}

6. Deep analysis report (exclusive)

Section	Content
1. Profile	Followers/following/likes/bio/verification/country
2. Core metrics	Median plays, viral count, engagement rate, cadence, gaps
3. Paid traffic	Platform-flagged ads (isAd) + heuristic suspect list
4. Top videos	Top10 detail
5. Captions	All captions Top10 + full CSV
6. Hashtags	Full frequency stats
7. Music	BGM usage frequency
8. Risk signals	Suspected bots, abnormal growth alerts
9. Followers	Coming soon (not available during beta)

Case study: Princess Bride Diamonds full report (2,730 videos)

7. Pricing

Free during beta (registration required, 10 tasks/day per user). Official pricing coming soon.

Full data download: bundled with the paid report. All CSVs (videos/captions/hashtags/music) are downloadable from the report page, available only to the report buyer.

8. Error codes

errorCode	Meaning
`NOT_FOUND`	Account does not exist
`PROFILE_PRIVATE`	Account is private
`PROFILE_EMPTY`	No videos on the account
`RATE_LIMITED`	Collection timed out / rate limited, retry later
`INVALID_INPUT`	Bad input parameters

9. Architecture (frontend-backend separation)

TKLens uses a separated architecture — the core engine never leaves the server:

Frontend (browser): only receives rendered HTML reports and JSON data, no source code visible
Backend (server): collection, analysis, and report generation all run in server-side Python
Interfaces: Web API + MCP, token auth, usage-based billing

Core assets (analysis algorithms, collection strategies) stay server-side — the technical basis for the pricing model.

10. API & MCP integration

Endpoint	Description
`POST api/register`	Sign up {email, password}
`POST api/login`	Log in
`POST api/tasks`	Submit {handle, proxy} (login required; proxy required, http/socks5)
`GET api/tasks`	Task list (login required)
`GET r/{id}.html`	HTML report (owner only)

Auth: Authorization: Bearer <token> or cookie tklens_token.

MCP: POST /mcp, JSON-RPC 2.0, 7 tools (traverse_account, analyze_account, normalize_video, normalize_profile, extract_hashtags, detect_ad, export_report).

11. FAQ

How long until the report?
Video analysis: queued in background, usually within a few hours (up to 24h for large accounts). Watch status in the console. Follower data is T+1 (~24h) and not available during beta.

Private accounts?
Public accounts only.

How accurate?
Plays/followers are snapshots at collection time; isAd is platform-verified.

How is this different from other data platforms?
Other platforms sell raw data (per-item pricing); TKLens sells conclusions (per-account pricing) with zero signature cost on full collection. Paid-traffic detection, viral attribution, and risk signals are layers they do not offer.

Is it legal?
Only publicly shared information is collected. Reports are for research and analysis.

Is my data isolated?
Each user's tasks, reports, and downloads are fully isolated — you only see your own. All query history is kept permanently.

Which IP is used for scraping?
Proxy required, never server IP. Supports http:// and socks5:// (SS/V2Ray OK), e.g. socks5://user:pass@host:port. Tasks without proxy will be rejected.