It fetches public TikTok data: Explore category videos, users, hashtags, sounds, comments, and more.

Needs Python 3.9+. TikTok changes endpoints often, so if something breaks, open an issue

The Dockerfile installs this repo with pip install .. Rebuild after you change code (COPY . . is from build time).

docker build . -t viralapi:latest
docker run --rm --ipc=host viralapi:latest python3 -m examples.explore_category_example

Pass secrets at run time. Do not bake ms_token into the image.

export ms_token="paste_the_cookie_value_here"
docker run --rm --ipc=host -e ms_token="$ms_token" viralapi:latest python3 -m examples.trending_example

.env is gitignored. Inject it without copying it into the image:

docker run --rm --ipc=host --env-file .env viralapi:latest python3 -m examples.explore_category_example

Explore with a JSON file on the host (files inside the container vanish on --rm unless you mount a volume):

docker run --rm --ipc=host -v "$PWD:/out" \
  -e CATEGORY=technology -e COUNT=30 -e OUTPUT=/out/technology.json \
  viralapi:latest \
  python3 -m examples.explore_category_example

pip install ViralApi
python -m playwright install

From this repo (includes local extras such as proxyproviders):

pip install .
python -m playwright install

Examples read the env var ms_token. In the browser the cookie is named msToken.

You do not need to be logged in. Wait until tiktok.com finishes loading (scroll the feed once). Examples live in examples/.

Chrome / Edge / Brave: open tiktok.com → DevTools (F12 or Cmd+Option+I) → Application → Cookies → https://www.tiktok.com → copy msToken.

Safari: Develop → Show Web Inspector → Storage → Cookies → www.tiktok.com.

Firefox: F12 → Storage → Cookies → https://www.tiktok.com.

export ms_token="paste_the_msToken_value_here"

import os
ms_token = os.environ.get("ms_token")
# await api.create_sessions(ms_tokens=[ms_token], ...)

• It expires. Copy a new one if requests start failing.
• For search, run a search on tiktok.com first, then copy the cookie.
• Keep it out of git. Use the env var or a local .env (already gitignored).
• You can pass ms_tokens=None and Playwright may create one. Explore often works better that way than with a stale cookie.

api.trending.videos() hits the For You feed (recommend/item_list). TikTok often returns an empty body for that. Use Explore instead:

https://www.tiktok.com/api/explore/item_list/ with categoryType. IDs come from the live Explore chips (data-e2e="explore-category-chip") and are listed in examples/explore_category_example.py.

There is no Apps category. Closest: Technology (118), then Games (103).

CATEGORY=technology COUNT=30 python -m examples.explore_category_example

HEADLESS=0 shows the browser. Leave ms_token unset unless the cookie is fresh. Language follows your IP, not the library region field.

Printing only goes to the terminal. Set OUTPUT to write a file (id, url, author, caption, plays, likes, comments, shares, hashtags, duration, sound). SAVE_RAW=1 also stores each video’s full as_dict.

CATEGORY=technology COUNT=30 OUTPUT=technology.json python -m examples.explore_category_example

from ViralApi import ViralApi
import asyncio
import os

ms_token = os.environ.get("ms_token", None)

async def trending_videos():
    async with ViralApi() as api:
        await api.create_sessions(
            ms_tokens=[ms_token],
            num_sessions=1,
            sleep_after=3,
            browser=os.getenv("TIKTOK_BROWSER", "chromium"),
        )
        async for video in api.trending.videos(count=30):
            print(video)
            print(video.as_dict)

if __name__ == "__main__":
    asyncio.run(trending_videos())

python -m examples.trending_example

If that comes back empty, use Explore.

Full fields are on video.as_dict (plays, likes, caption, author, hashtags, …). TikTok changes that shape. Nothing is written to disk unless you set OUTPUT or write the file yourself.

• EmptyResponseException — TikTok is treating the client as a bot. A residential proxy often helps. ProxyProviders: create_sessions(proxy_provider=...). See examples/proxy_provider_example.py.
• Browser has no attribute — run python3 -m playwright install. If it still fails, use the playwright-python quickstart.
• Got a Coroutine — most methods are async; await them.

• @ Viralway
• @ Microsoft Playwright