TikTok Scraper API Guide: Profiles, Posts, and Shop Data

TL;DR:

• Three actors cover the core workflow. Use scraper.tiktok.user.detail for public account details, scraper.tiktok.user.work for a creator's public posts, and scraper.tiktok.shop.page for a Shop product page.
• The profile call is the bridge to post data. It accepts unique_id and returns sec_uid, which the posts actor expects.
• Shop requests need product context. Send both product_id and region; read the returned region and currency before comparing records.
• The response is structured JSON. Store identifiers as strings, preserve nullable fields, and keep the raw response beside any normalized table.
• A TikTok scraper API returns snapshots. Scheduling, history, scoring, and alerts belong in the pipeline that calls it.
• Free to start. New Scrapeless accounts include free credit; create an account in the Scrapeless Dashboard.

Introduction: one endpoint, three useful TikTok datasets

TikTok data projects usually begin with a simple question: which public account, post, or product fields can a workflow collect without maintaining a browser parser? The answer depends on the object. A creator profile, a creator's post feed, and a Shop product page have different identifiers and response shapes.

The Scrapeless TikTok scraper API exposes those objects through managed actors behind one request endpoint. The API returns JSON over HTTP, so it fits scripts, data jobs, internal tools, and agent workflows. This guide maps the actors, sends authenticated requests, and turns their responses into records that remain understandable after the first run.

For a wider view of managed actors, read the Scrapeless Scraper API guide.

What the TikTok Scraper API Does

The API accepts a JSON request containing an actor name and an input object. Scrapeless runs the actor and returns the actor's structured result. The transport follows standard HTTP request semantics described in the HTTP Semantics specification, while the response body uses the registered JSON media type listed by IANA's media type registry.

The three TikTok actors serve different jobs:

These surfaces do not provide follower lists, audience demographics, comment text, a complete TikTok catalog, or an order ledger. Treat every response as a point-in-time observation of the requested public object.

What You Can Build With It

• Creator research. Join profile statistics with a recent post sample before a human reviews brand fit.
• Content monitoring. Capture descriptions, post URLs, timestamps, hashtags, and public engagement counts for selected accounts.
• Catalog checks. Read a known Shop product by ID and region, including price, currency, stock, and variant information.
• Product snapshots. Save repeated product responses with collection timestamps to build a history table.
• Internal enrichment. Add public TikTok fields to an existing creator or product record without scraping rendered page markup.

Endpoints and Parameters

All three actors use the same endpoint:

POST https://api.scrapeless.com/api/v1/scraper/request

Authentication uses the x-api-token request header. The body contains actor and input.

Profile parameters

scraper.tiktok.user.detail accepts unique_id, the username without the leading @. Its response can include account_id, unique_id, sec_uid, nickname, profile URL, bio, avatar, public account statistics, account creation time, language, country, and boolean flags such as verification, privacy, and seller status.

Post parameters

scraper.tiktok.user.work requires sec_uid. It also accepts cursor as a string and count as a positive integer. The default cursor is 0, and the documented default count is 35. A response contains an items array. Do not invent a continuation field: advance only when the response and current documentation provide a verified continuation value for the workflow.

Shop parameters

scraper.tiktok.shop.page requires product_id and region. Region examples in the documentation include GB, SG, JP, and US; they are examples rather than an exhaustive market list. The response's region represents the product page that resolved and should travel with the price and currency.

The actor details are available in the TikTok user detail documentation, TikTok user work documentation, and TikTok Shop page documentation.

Prerequisites

• A Scrapeless account and API token from the Scrapeless Dashboard
• A public TikTok username or known TikTok Shop product ID
• A permitted purpose and a retention policy for the data being collected

The examples require a live Scrapeless API token. Export it as SCRAPELESS_API_KEY before running the code.

Send an Authenticated Request

This curl call fetches public profile data. Replace the username with the account that your workflow is authorized to research.

curl --request POST 'https://api.scrapeless.com/api/v1/scraper/request' \
  --header "x-api-token: ${SCRAPELESS_API_KEY}" \
  --header 'content-type: application/json' \
  --data '{
    "actor": "scraper.tiktok.user.detail",
    "input": {"unique_id": "tiktok"}
  }'

The same envelope works for the other actors. Only the actor and input fields change.

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.

Join Profile and Post Data in Python

The useful join key is sec_uid. The following program gets it from the profile response, then requests a bounded post sample. Python's JSON library documentation explains the serialization behavior used here.

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

ENDPOINT = "https://api.scrapeless.com/api/v1/scraper/request"
TOKEN = os.environ["SCRAPELESS_API_KEY"]


def run_actor(actor, actor_input):
    body = json.dumps({"actor": actor, "input": actor_input}).encode()
    request = Request(
        ENDPOINT,
        data=body,
        headers={
            "x-api-token": TOKEN,
            "content-type": "application/json",
        },
        method="POST",
    )
    with urlopen(request, timeout=60) as response:
        return json.load(response)


profile = run_actor(
    "scraper.tiktok.user.detail",
    {"unique_id": "tiktok"},
)

posts = run_actor(
    "scraper.tiktok.user.work",
    {"sec_uid": profile["sec_uid"], "cursor": "0", "count": 10},
)

record = {
    "profile": {
        "account_id": str(profile.get("account_id", "")),
        "unique_id": profile.get("unique_id"),
        "sec_uid": profile.get("sec_uid"),
        "nickname": profile.get("nickname"),
        "statistics": profile.get("statistics", {}),
    },
    "posts": posts.get("items", []),
}

print(json.dumps(record, ensure_ascii=False, indent=2))

Keep IDs as strings even when they contain only digits. That avoids precision loss in downstream tools that represent large numbers with limited numeric precision.

Read the Response Schema Without Guessing

Profile, post, and Shop responses need separate normalization rules.

For profiles, keep identity fields beside the nested statistics object. For posts, preserve the post ID and URL, description, creation time, public counts, media fields, hashtags, language, pinned or ad flags, music, subtitles, and permissions when present. Media URLs and subtitles can be blank, so an empty value is different from a failed request.

For Shop products, separate product-level fields from SKU-level fields. The displayed price, aggregate stock, seller, categories, and shipping details describe the product response. Each SKU can have its own options and availability. sold_count is the value returned by the product page; it is not a verified order ledger or a period-specific GMV figure.

Handling Structured Output

A durable table starts with four choices:

1. Add a collection timestamp outside the actor response.
2. Preserve the raw JSON for audit and reprocessing.
3. Normalize profiles, posts, products, and SKUs into separate tables.
4. Treat absent and empty fields as unknown until the source semantics establish another meaning.

For personal data, collect only the public fields needed for the stated purpose. The NIST Privacy Framework offers a useful structure for identifying privacy risk and setting controls around collection, access, and retention.

Scrapeless packages these actors under Scraping API. Check the current pricing page before estimating production volume.

Common Problems to Prevent

• Using a username where sec_uid is required. Resolve the profile first and pass its sec_uid to the posts actor.
• Treating every blank media field as an error. Optional fields can be empty in a valid response.
• Merging product and SKU stock. Keep both levels so a variant change does not overwrite the product snapshot.
• Comparing prices without region and currency. Store both fields on every observation.
• Calling a snapshot a tracker. A tracker needs a scheduler, timestamped storage, comparison logic, and an alert destination.

Conclusion: build around stable objects

The TikTok scraper API reduces three common jobs to clear actor calls: resolve an account, collect a bounded public post sample, or fetch a known Shop product in a region. The main engineering work moves to data modeling: preserve identifiers, keep raw responses, attach timestamps, and separate product records from variants.

Ready to Build Your TikTok Data Pipeline?

Join the Scrapeless Discord or Telegram community to compare implementation notes. Create an account in the Scrapeless Dashboard when you are ready to send the first request.

FAQ

Q: What is a TikTok scraper API?

A TikTok scraper API converts supported public TikTok pages into structured data through an HTTP request. Scrapeless exposes separate actors for user details, user posts, and Shop product pages.

Q: Can the API get posts from a TikTok username?

Yes, through a two-call workflow. Resolve the username with scraper.tiktok.user.detail, then pass the returned sec_uid to scraper.tiktok.user.work.

Q: Does the API return comments or follower lists?

No. The documented actors covered here do not return comment text, follower lists, or audience demographics.

Q: Does a TikTok Shop response include SKU data?

Yes. The Shop actor can return options and SKU records alongside product-level price, currency, stock, seller, category, image, rating, review, and shipping fields.

Q: Is scraping public TikTok data legal?

Legality depends on the jurisdiction, data, purpose, access method, and applicable terms. Use public data only, minimize collection, protect stored records, and obtain legal advice for the specific project.

Q: Do I need to manage proxies or page defenses?

The managed actor handles the collection surface behind the API call. Your application still needs valid inputs, clear error handling, and conservative request planning.

Q: Can the workflow run without an AI agent?

Yes. Any HTTP client that can send JSON and the x-api-token header can call the endpoint.