TikTok Scraper endpoints

Choose the TikTok actor for the data you need. Each operation uses the same HTTP request endpoint, but its actor and input fields differ.

Request and authentication

POST https://api.scrapeless.com/api/v1/scraper/request
x-api-token: YOUR_API_KEY
Content-Type: application/json

Replace YOUR_API_KEY with your Scrapeless API key. Send one JSON object containing actor and input.

Choose an operation

User Detail

Pass the account username in unique_id, as shown in the official example:

curl --request POST 'https://api.scrapeless.com/api/v1/scraper/request' \
  --header 'x-api-token: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "actor": "scraper.tiktok.user.detail",
  "input": {
    "unique_id": "teamtrump"
  }
}'

The published response includes account_id, unique_id, sec_uid, nickname, profile_url, avatar, statistics, and account flags such as is_verified.

Save sec_uid if you want to call User Work. A username, account ID, and sec_uid are separate values; do not substitute one for another.

User Detail API reference

User Work

Retrieve an account’s posts using its sec_uid. The request below uses the same account identifier as the official User Detail response; replace it with the sec_uid from your own completed profile request.

curl --request POST 'https://api.scrapeless.com/api/v1/scraper/request' \
  --header 'x-api-token: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "actor": "scraper.tiktok.user.work",
  "input": {
    "sec_uid": "MS4wLjABAAAAIb0gpCf24bC1i5TWl87J5SjS0h7ZB59nfledznAyQ_DF7-vpgJJ8nYfzo98Ba3fp",
    "cursor": "0",
    "count": 10
  }
}'

The successful example contains an items array. This excerpt retains selected fields from its first item:

{
  "items": [
    {
      "post_id": "7673888001365150989",
      "post_url": "https://www.tiktok.com/@teamtrump/video/7673888001365150989",
      "play_count": 572300,
      "like_count": 31000
    }
  ]
}

The full item also includes video and author information. The reference documents a cursor input but its response example does not include a next-page cursor or has_more field. Do not construct a pagination loop that assumes either field exists.

User Work API reference

Shop Page

Retrieve product details with a TikTok Shop product ID and region. Both inputs are required strings. This request retains the official example’s gb value:

curl --request POST 'https://api.scrapeless.com/api/v1/scraper/request' \
  --header 'x-api-token: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "actor": "scraper.tiktok.shop.page",
  "input": {
    "product_id": "1729411983267761850",
    "region": "gb"
  }
}'

The returned region represents the actual region on the product page. This subset of the published example shows the field types; prices and counts are historical example values:

{
  "product_id": "1729411983267761850",
  "region": "GB",
  "sold_count": "17644",
  "price": {
    "currency": "GBP",
    "sale_price": "5.78"
  },
  "rating": 4.5,
  "review_count": "823"
}

The full example also includes stock, images, options, skus, seller, and shipping_options. Keep product IDs as strings; the example also represents sold_count, review_count, and price.sale_price as strings.

Shop Page API reference

Handle task results

An HTTP 200 response contains the completed result. An HTTP 201 response means processing is still underway; save its taskId and retrieve that task with:

curl --request GET 'https://api.scrapeless.com/api/v1/scraper/result/YOUR_TASK_ID' \
  --header 'x-api-token: YOUR_API_KEY'

Replace YOUR_TASK_ID with the ID returned by your request. Follow Results and Polling for polling intervals and retry limits.

Inspect error bodies as well as HTTP status codes. A 400 response can include code: 20500 and message: "scraping failed"; it is not a successful data response. Check the target and request inputs before retrying.

Response examples

The excerpts on this page are subsets of official API examples, not live results from the sample requests. Read the linked operation reference for the full payload and handle missing values according to your application’s needs.