TikTok's Research API is only for approved researchers: academics and not-for-profit organizations in eligible regions, reviewed project by project. Creators, advertisers and commercial users are not eligible, and a developer account alone does not give access. For public TikTok data without approval, ToolzerHub's /v1 routes return profiles and videos by hashtag.
Who TikTok lets apply
TikTok's pages now title it Research Tools. It accepts three kinds of applicant:
- Academic institutions in the U.S., EEA, UK, Canada or Switzerland.
- Not-for-profit or independent research bodies in the EU.
- Academic institutions or not-for-profits in Brazil studying online youth safety.
Applicants must be independent of commercial interests, disclose funding, submit a research proposal and show an ethical review. You create a TikTok for Developers account with a professional email, submit the form and wait; TikTok says a reply typically takes 4 weeks.
What approved researchers get
There is no API key before approval. After it, TikTok generates a client key and secret, which you exchange for an access token. The API covers video queries, user info, comments, followers, following, liked, pinned and reposted videos, playlists and EU TikTok Shop data.
Video queries filter by region_code, keyword, hashtag_name and username, return up to 100 videos, and cover a creation-date window of at most 30 days. The quota is 1,000 requests and 100,000 records a day across the APIs. The video search runs on an archive, so new videos take up to 48 hours to appear.
What you can read without research approval
TikTok's other official route is the Display API, for showing a creator's videos and profile in your product. Its video list returns a user's public videos, newest first, up to 20 per page, with a token from that user. It reads accounts that sign in to your app, not arbitrary public accounts.
| Research Tools | Display API | ToolzerHub | |
|---|---|---|---|
| Who | Researchers | Sign-in apps | API key |
| Data | Public accounts | Signed-in user | Profiles, tags |
| Per call | 100 videos | 20 videos | 30 videos |
If you qualify as a researcher, use Research Tools: it also covers comments, follower and following lists, and keyword and region search, which our /v1 routes do not. Our /v2 TikTok routes add a user's video list, comments, followers and following at 2 credits a call.
Get public TikTok data with ToolzerHub
We make ToolzerHub. Our TikTok API reads public data with one API key and no TikTok app, login or approval. The /v1 routes are profile, video, hashtag, hashtag videos and videos by sound, 1 credit per call each. The profile route returns an account's stats, rounded to three significant figures, not its recent videos, so you list videos through a hashtag or a sound. To list one account's own videos, see getting a TikTok user's videos.
This script writes profiles and a hashtag's videos to two CSV files; prefix hashtags with #.
import csv
import os
import sys
import time
from datetime import datetime, timezone
import requests
BASE = "https://api.toolzerhub.com/v1/tiktok"
HEADERS = {"x-api-key": os.environ.get("TOOLZERHUB_API_KEY", "")}
PROFILE_FIELDS = ["username", "user_id", "nickname", "verified", "followers", "following",
"likes", "videos", "bio"]
VIDEO_FIELDS = ["hashtag", "video_id", "author", "posted", "plays", "likes", "comments",
"shares", "saves", "description", "url"]
calls = 0
def cell(value):
# Spreadsheets run text that starts with = + - or @ as a formula; an apostrophe keeps it text.
if isinstance(value, str) and value[:1] in ("=", "+", "-", "@", "\t", "\r"):
return "'" + value
return value
def get(path, params, tries=5):
# 429 and 503 are retryable; the error body may say how long to wait.
global calls
for attempt in range(tries):
r = requests.get(f"{BASE}/{path}", headers=HEADERS, params=params, timeout=90)
calls += 1
if r.status_code == 400: # malformed username or hashtag: skip it, keep the rest of the run
print("bad request:", r.json()["error"]["message"].splitlines()[0])
return None
if r.status_code not in (429, 503) or attempt == tries - 1:
r.raise_for_status()
return r.json().get("data") # None when the account or hashtag does not exist
try:
wait = r.json()["error"]["details"]["retryAfter"]
except (ValueError, KeyError, TypeError):
wait = 5 * (attempt + 1)
time.sleep(min(wait, 60))
def profile_row(data):
user, stats = data["user"], data.get("stats") or {}
return {
"username": user["unique_id"], "user_id": user["id"], "nickname": user.get("nickname"),
"verified": user.get("verified"), "followers": stats.get("follower_count"),
"following": stats.get("following_count"), "likes": stats.get("heart_count"),
"videos": stats.get("video_count"),
"bio": (user.get("signature") or "").replace("\n", " "),
}
def video_row(tag, v):
stats, stats_v2 = v.get("stats") or {}, v.get("stats_v2") or {}
posted = v.get("create_time")
return {
"hashtag": tag, "video_id": v["id"], "author": v["author"]["unique_id"],
"posted": datetime.fromtimestamp(posted, timezone.utc).date().isoformat() if posted else "",
"plays": stats.get("play_count"), "likes": stats.get("digg_count"),
"comments": stats.get("comment_count"), "shares": stats.get("share_count"),
"saves": stats_v2.get("collectCount"),
"description": (v.get("desc") or "").replace("\n", " "),
"url": f"https://www.tiktok.com/@{v['author']['unique_id']}/video/{v['id']}",
}
def hashtag_videos(tag, max_pages):
# A hashtag name resolves to a numeric challenge id; then page with the cursor.
info = get("hashtag", {"hashtag": tag})
if not info:
print(f"skipped #{tag}: no such hashtag")
return
params = {"challenge_id": info["id"], "count": 30}
for _ in range(max_pages):
data = get("hashtag_videos", params)
if not data or not data["entries"]:
return
yield from data["entries"]
if not data["has_more"]:
return
params["cursor"] = data["next_cursor"]
def main(sources, pages="2", prefix="tiktok"):
people, tags = [], []
for s in [s.strip() for s in sources.split(",") if s.strip()]:
(tags if s.startswith("#") else people).append(s.lstrip("#@"))
seen, n_profiles = set(), 0
with open(f"{prefix}_profiles.csv", "w", newline="", encoding="utf-8") as pf, \
open(f"{prefix}_videos.csv", "w", newline="", encoding="utf-8") as vf:
profiles = csv.DictWriter(pf, fieldnames=PROFILE_FIELDS)
videos = csv.DictWriter(vf, fieldnames=VIDEO_FIELDS)
profiles.writeheader()
videos.writeheader()
for name in people:
data = get("profile", {"username": name})
stats = (data or {}).get("stats") or {}
if data and not stats.get("follower_count") and stats.get("video_count"):
data = get("profile", {"username": name}) # zero followers with videos: ask once more
if not data: # unknown usernames return 200 with data null
print(f"skipped {name}: no such account")
continue
n_profiles += 1
profiles.writerow({k: cell(v) for k, v in profile_row(data).items()})
for tag in tags:
for v in hashtag_videos(tag, int(pages)):
if v["id"] not in seen: # pages can overlap
seen.add(v["id"])
videos.writerow({k: cell(x) for k, x in video_row(tag, v).items()})
print(f"wrote {n_profiles} profiles and {len(seen)} videos in {calls} calls")
if __name__ == "__main__":
if len(sys.argv) < 2:
sys.exit('usage: python tiktok_export.py "nasa,nba,#space" [pages_per_hashtag] [file_prefix]')
if not HEADERS["x-api-key"]:
sys.exit("set TOOLZERHUB_API_KEY first")
main(*sys.argv[1:])
export TOOLZERHUB_API_KEY=your_key
python tiktok_export.py "tiktok,nasa,nba,natgeo,#space" 2
wrote 4 profiles and 60 videos in 7 calls
The profile file, trimmed:
| username | followers | following | videos |
|---|---|---|---|
| tiktok | 96,300,000 | 1 | 1,510 |
| nasa | 2,100,000 | 23 | 57 |
| nba | 27,300,000 | 267 | 24,300 |
| natgeo | 9,700,000 | 62 | 1,539 |
The follower counts have three significant figures, so use them for size, not daily growth. The two #space pages gave 60 unique videos from 54 accounts, in no date order, with a median of 503,050 plays and 54,500 likes.
A hashtag listing is a sample, not an archive: #space ended after 6 pages with 160 unique videos (13 repeats) and #nasa after 7 pages with 167 (22 repeats). The script drops repeats by video_id, and the TikTok hashtag API guide covers hashtag listings on their own. A video_id has 19 digits, so import it into Excel as Text.
What it costs
Each /v1 call is 1 credit, so the run above cost 7 credits. A whole hashtag listing is 1 lookup plus 6 or 7 pages: 7 or 8 credits for about 160 unique videos. You get 100 free credits a month; $19 buys 10,000 credits that never expire, and plans for higher volume cover more accounts and hashtags. Set your key and run the script on your first account.
For keyword search without research approval, see the TikTok search API. Other official APIs that closed or restricted access: what X's API costs and the Instagram Basic Display API replacement.
We are not affiliated with TikTok or ByteDance.