How to Scrape TikTok Profiles with Python and Scrapeless

TL;DR:

• A profile lookup starts with the username. Pass unique_id without @ to scraper.tiktok.user.detail.
• The response contains identity and public account fields. It can include account_id, sec_uid, nickname, profile URL, bio, avatar, statistics, locale fields, and account-state flags.
• sec_uid unlocks the next step. Save it when a workflow will request the account's public posts.
• Identifiers should stay strings. Large numeric-looking IDs can lose precision when downstream systems coerce them to numbers.
• Profile data is not audience data. The actor does not expose follower lists or audience demographics.
• Free to start. New Scrapeless accounts include free credit through the Scrapeless Dashboard.

Introduction: resolve a public account into a stable record

A username is convenient for input, but it is only one part of a useful creator record. A research or monitoring job also needs a stable account identifier, the sec_uid required by the post actor, public statistics, and enough context to distinguish accounts with similar display names.

The Scrapeless TikTok profile scraper packages that lookup as one JSON request. Python can then validate the response, choose the needed fields, and store a compact record without parsing rendered HTML. For the broader actor map, see the Scrapeless Scraper API guide.

What the Profile Actor Returns

scraper.tiktok.user.detail accepts unique_id, the visible username without the leading @. A successful response can include:

• account_id, unique_id, and sec_uid
• nickname, profile URL, biography, and avatar
• follower, following, friend, like, video, and liked-video statistics
• account creation time, language, and country
• verification, privacy, and seller flags

Fields can be absent or empty. A private-account flag is an account state, not permission to access private content. This guide uses only the documented public profile response.

Why Use Scrapeless Scraping API

Scrapeless runs the TikTok profile actor behind a single HTTP endpoint and returns structured JSON. That gives Python jobs a consistent request envelope and removes page-selector code from the application.

The API surface is documented in the TikTok user detail reference. Scrapeless groups the actor under Scraping API; check current pricing before setting a production collection schedule.

Prerequisites

• Python with the standard library
• A Scrapeless account and API token from the Scrapeless Dashboard
• A public TikTok username relevant to the project
• A defined field list, purpose, and retention period

The example requires a live token in SCRAPELESS_API_KEY. Supply the username through TIKTOK_USERNAME without @.

Request a TikTok Profile in Python

The code uses Python's built-in HTTP and JSON modules. The urllib.request documentation covers the request object, while the JSON module documentation defines the encoder and decoder used below.

import json
import os
from urllib.error import HTTPError
from urllib.request import Request, urlopen

ENDPOINT = "https://api.scrapeless.com/api/v1/scraper/request"


def get_profile(unique_id):
    payload = {
        "actor": "scraper.tiktok.user.detail",
        "input": {"unique_id": unique_id.lstrip("@")},
    }
    request = Request(
        ENDPOINT,
        data=json.dumps(payload).encode(),
        headers={
            "x-api-token": os.environ["SCRAPELESS_API_KEY"],
            "content-type": "application/json",
        },
        method="POST",
    )
    try:
        with urlopen(request, timeout=60) as response:
            return json.load(response)
    except HTTPError as exc:
        detail = exc.read().decode("utf-8", errors="replace")
        raise RuntimeError(f"profile request failed: {exc.code} {detail}") from exc


profile = get_profile(os.environ["TIKTOK_USERNAME"])
normalized = {
    "account_id": str(profile.get("account_id", "")),
    "unique_id": profile.get("unique_id"),
    "sec_uid": profile.get("sec_uid"),
    "nickname": profile.get("nickname"),
    "profile_url": profile.get("profile_url"),
    "bio": profile.get("bio"),
    "statistics": profile.get("statistics") or {},
    "language": profile.get("language"),
    "country": profile.get("country"),
    "is_verified": profile.get("is_verified"),
    "is_private": profile.get("is_private"),
    "is_seller": profile.get("is_seller"),
}
print(json.dumps(normalized, ensure_ascii=False, indent=2))

Start Scraping with Scrapeless

Power up your web scraping and automation workflow with Scrapeless!
Sign up today and get $5 in free credit — no credit card required.

Claim your free credit now in the Scrapeless Dashboard.

Map the Response to Your Data Model

Keep three identity fields

unique_id is the human-readable account handle. account_id is an account identifier. sec_uid is the input needed by scraper.tiktok.user.work. Keep all three rather than choosing one universal key.

Preserve the statistics object

Public counts are point-in-time values. A normalized analytics table can extract selected counts, but the raw statistics object should remain available so a schema change does not erase source context.

Treat account flags as nullable

Verification, privacy, and seller flags are useful when present. If a field is absent, store unknown rather than false. The same rule applies to language, country, bio, and avatar.

Attach your own collection timestamp

The profile response describes the account when the actor ran. Add a UTC observation timestamp in the calling application and keep it separate from any account creation time returned by TikTok.

Get sec_uid From a Username

The profile request is the documented bridge from username to post collection. After storing sec_uid, a second request can use scraper.tiktok.user.work with cursor and count. The user work actor reference describes those inputs.

Avoid deriving sec_uid from a profile URL or treating it as interchangeable with the username. Use the returned field. If it is absent, keep the profile record and mark post collection as unavailable for that observation.

Validate Before Export

A small set of checks prevents misleading rows:

1. Confirm unique_id matches the intended account after case and leading-@ normalization.
2. Keep account_id as a string.
3. Accept empty biography, locale, or avatar values.
4. Require sec_uid only when the next job needs posts.
5. Record the HTTP status and a redacted error body when a request fails.

The endpoint uses normal HTTP semantics; RFC 9110 is the primary reference for status-code meaning. Application logs should never include the API token.

Handle Public Profile Data Responsibly

Collect the smallest field set that answers the research question. Restrict access to stored profile records, delete data when the retention period ends, and avoid using public counts to infer sensitive traits. The NIST Privacy Framework provides a practical vocabulary for mapping data processing to privacy risk.

A profile response supports account-level research. It does not provide the identity of followers, audience demographics, private posts, or permission for unrelated profiling.

Conclusion: use the profile as the identity layer

A TikTok profile scraper should produce a stable, minimal account record from a username. Save account_id, unique_id, and sec_uid, preserve nullable fields, timestamp the observation, and pass sec_uid forward only when a post workflow needs it.

Ready to Build Your TikTok Profile Dataset?

Join the Scrapeless Discord or Telegram community for implementation discussion. Create an account in the Scrapeless Dashboard when the field list and storage policy are ready.

FAQ

Q: What input does the TikTok profile scraper need?

It needs unique_id, which is the public username without the leading @.

Q: What is sec_uid used for?

sec_uid is the account identifier required by the documented user-work actor that returns public posts.

Q: Can the profile actor return follower demographics?

No. It returns public profile fields and account statistics, not audience demographics or follower lists.

Q: Should TikTok account IDs be stored as numbers?

No. Store numeric-looking identifiers as strings to preserve every digit across databases and analytics tools.

Q: Is scraping a public TikTok profile legal?

Legality depends on the jurisdiction, purpose, access method, data, and applicable terms. Use public fields only, minimize collection, and obtain legal advice for the planned use.

Q: Does the workflow need a proxy or DOM parser?

No DOM parser appears in the application code because the managed actor returns structured data. Scrapeless handles the underlying collection surface.

Q: Can this run without an AI agent?

Yes. The Python example is a direct HTTP client and runs independently of an agent.