TikTok Scraper API

Scraping is asynchronous: submit run → poll → fetch data. For the full flow see Quick Start; for the shared envelope / run state machine / billing / error codes see Auth & Error Handling. This page only lists each endpoint's target fields and output fields.

Quick Reference

• Base URL: https://api.antsdata.com/v1
• Method & path: submitting a run is always POST /v1/scraper/tiktok/<resource>; polling / fetching / downloading use the shared GET /v1/scraper/runs/{id} (see Quick Start)
• Auth: header Authorization: Bearer ants_xxx (static API key)
• Content-Type: application/json
• Request body: always { "deliveryMode": "async", "recordLimit": 1000, "targets": [ … ] }; the fields of each targets[] element are listed under each endpoint's "target fields". One run may hold multiple targets (per-target outcome is reported in the tasks[] returned by polling).

💡 You can also use deliveryMode: "sync" (small jobs block until terminal, auto fallback to polling on timeout) — see quick-start · Sync mode.

Endpoints at a Glance

profile and profile-url return the same output; they differ only in the input entry: profile is username-first, profile-url is URL-first (each endpoint also accepts the other field — supply either one).

Profile — Account Data (by Username)

POST /v1/scraper/tiktok/profile

Target fields (each element of targets[]):

Output fields (each item in records' items[] when fetching data):

Submit example:

curl -X POST "https://api.antsdata.com/v1/scraper/tiktok/profile" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "deliveryMode": "async",
    "recordLimit": 1000,
    "targets": [
      { "username": "khaby.lame" },
      { "username": "nike" }
    ]
  }'

Returns HTTP 201 + { "id": <run id>, "status": "queued" }; then poll and fetch data as in Quick Start.

Profile URL — Account Data (by Profile URL)

POST /v1/scraper/tiktok/profile-url

Target fields (each element of targets[]):

Output fields (each item in records' items[] when fetching data):

Submit example:

curl -X POST "https://api.antsdata.com/v1/scraper/tiktok/profile-url" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "deliveryMode": "async",
    "recordLimit": 1000,
    "targets": [
      { "profileUrl": "https://www.tiktok.com/@khaby.lame" }
    ]
  }'

Returns HTTP 201 + { "id": <run id>, "status": "queued" }; then poll and fetch data as in Quick Start.

Videos — Account Videos

POST /v1/scraper/tiktok/videos

Target fields (each element of targets[]):

Output fields (each item in records' items[] when fetching data):

Submit example:

curl -X POST "https://api.antsdata.com/v1/scraper/tiktok/videos" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "deliveryMode": "async",
    "recordLimit": 1000,
    "targets": [
      { "username": "khaby.lame", "sortBy": "popular" }
    ]
  }'

Returns HTTP 201 + { "id": <run id>, "status": "queued" }; then poll and fetch data as in Quick Start.

Hashtag — Hashtag Videos

POST /v1/scraper/tiktok/hashtag

Target fields (each element of targets[]):

Output fields (each item in records' items[] when fetching data):

Submit example:

curl -X POST "https://api.antsdata.com/v1/scraper/tiktok/hashtag" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "deliveryMode": "async",
    "recordLimit": 1000,
    "targets": [
      { "hashtag": "comedy" }
    ]
  }'

Returns HTTP 201 + { "id": <run id>, "status": "queued" }; then poll and fetch data as in Quick Start.

Search — Keyword Search

POST /v1/scraper/tiktok/search

Target fields (each element of targets[]):

Output fields (each item in records' items[] when fetching data):

Submit example:

curl -X POST "https://api.antsdata.com/v1/scraper/tiktok/search" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "deliveryMode": "async",
    "recordLimit": 1000,
    "targets": [
      { "keyword": "web scraping" }
    ]
  }'

Returns HTTP 201 + { "id": <run id>, "status": "queued" }; then poll and fetch data as in Quick Start.

Comments — Video Comments

POST /v1/scraper/tiktok/comments

Target fields (each element of targets[]):

Output fields (each item in records' items[] when fetching data):

Submit example:

curl -X POST "https://api.antsdata.com/v1/scraper/tiktok/comments" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "deliveryMode": "async",
    "recordLimit": 1000,
    "targets": [
      {
        "videoUrl": "https://www.tiktok.com/@khaby.lame/video/7641693768831225101",
        "commentsLimit": 100,
        "includeReplies": true
      }
    ]
  }'

Returns HTTP 201 + { "id": <run id>, "status": "queued" }; then poll and fetch data as in Quick Start.

Fetching Data

After submitting, poll GET /v1/scraper/runs/{id} until succeeded, then page through GET /v1/scraper/runs/{id}/records?page=1&pageSize=20, or download the full result via GET /v1/scraper/runs/{id}/download?format=json|csv|excel (see Quick Start for the end-to-end example).

Next Steps

• Platform guides: X · Instagram · Facebook · LinkedIn · Google · YouTube · Amazon
• Synchronous search: Google SERP
• Auth & Error Handling — Unified envelope, run state machine, billing & error codes

FAQ

Q: Can one run scrape multiple accounts / hashtags / keywords?

Yes. targets is an array — a single run can hold multiple targets, and each target's outcome is reported in the tasks[] returned by polling (see Auth & Error Handling).

Q: What is the difference between profile and profile-url?

Both return exactly the same output; they differ only in the input entry: profile scrapes by username, profile-url scrapes by profile URL. Each endpoint also accepts the other field (username / profileUrl, supply either one) — pick the endpoint that matches the identifier you already have.

Q: How are private or nonexistent accounts handled?

That target is marked failed in tasks[] with an errorMessage while the other targets still produce data; failed targets are not billed (partial success is still settled by the number of successful records).

Q: Why does the videos endpoint no longer take searchMode?

The capability once merged under searchMode (user/hashtag/keyword) is now split into three dedicated endpoints: /videos for an account's videos, /hashtag for a hashtag, and /search for keyword search. Choose the endpoint directly — searchMode is no longer accepted.

Q: What format is the comments timestamp?

create_time is a Unix second-level timestamp (e.g. 1781827200); convert it to ISO 8601 yourself if you need a human-readable time.

Q: Is the data real-time?

Yes. Every run scrapes in real time and returns the target platform's current data.