Skip to main content
POST
/
tiktok
/
profile
Submit a TikTok profile scrape (async)
curl --request POST \
  --url https://api.vidnavigator.com/v1/tiktok/profile \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "profile_url": "https://www.tiktok.com/@tiktok",
  "max_posts": 100,
  "after_date": "20240101",
  "before_date": "20241231",
  "min_likes": 1,
  "max_likes": 1
}
'
{
  "status": "success",
  "data": {
    "task_id": "<string>",
    "task_status": "processing",
    "profile_url": "<string>",
    "expires_at": "2023-11-07T05:31:56Z",
    "check_status_url": "/v1/tiktok/profile/550e8400-e29b-41d4-a716-446655440000",
    "message": "<string>"
  }
}
Start an asynchronous scrape of a public TikTok profile and return a task_id immediately.

​
Overview

This endpoint is designed for profile-level collection, not single-video analysis. It starts a background scrape job that iterates through a TikTok account, applies your filters as it goes, and stores the results temporarily so you can fetch them later. Use it when you want to:
  • collect recent posts from a TikTok creator
  • filter videos by date or like count
  • scrape large profiles without blocking on a long request
  • export the full result set through a temporary download_url

​
How the Async Flow Works

  1. Send POST /tiktok/profile with a public TikTok profile_url and optional filters.
  2. The API accepts the task and returns a task_id with task_status: "processing".
  3. Poll GET /tiktok/profile/{task_id} until the task is completed or failed.
  4. Once completed, either page through videos using cursors or download the full JSON from download_url when available.
Results are temporary. Tasks expire about 1 hour after creation, including download_url availability.

​
Filters You Can Apply

All filters are optional except profile_url.
FieldTypeDescription
profile_urlstringPublic TikTok profile URL, such as https://www.tiktok.com/@username
max_postsintegerMaximum number of matching videos to return
after_datestringInclude only videos on or after this date, format YYYYMMDD
before_datestringInclude only videos on or before this date, format YYYYMMDD
min_likesintegerInclude only videos with at least this many likes
max_likesintegerInclude only videos with at most this many likes
max_posts and after_date are the most useful filters for keeping scrapes smaller and faster because they can stop pagination early.

​
What You Get Back Immediately

The submit endpoint now returns more than just a task ID. The accepted response includes:
  • task_id to identify the scrape job
  • task_status set to processing
  • profile_url echoing the submitted profile
  • expires_at so you know when the task record will expire
  • check_status_url with the relative API path to poll
  • message confirming the job was accepted

​
Example Request

curl -X POST "https://api.vidnavigator.com/v1/tiktok/profile" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "profile_url": "https://www.tiktok.com/@tiktok",
    "max_posts": 50,
    "after_date": "20240101",
    "min_likes": 10000
  }'

​
Success Response

The endpoint returns 202 Accepted because the scrape runs in the background. 
{
  "status": "success",
  "data": {
    "task_id": "tt_profile_abc123",
    "task_status": "processing",
    "profile_url": "https://www.tiktok.com/@tiktok",
    "expires_at": "2026-04-26T00:55:00Z",
    "check_status_url": "/v1/tiktok/profile/tt_profile_abc123",
    "message": "TikTok profile scrape accepted. Poll the status endpoint to retrieve results."
  }
}

​
Billing Notes

TikTok profile scraping is billed by pages consumed during the scrape:
  • each TikTok API page is billed as one standard_request when no proxy is used
  • each TikTok API page is billed as one residential_request when a residential proxy is used
  • one page is pre-charged when the task is accepted
  • final usage is reconciled when the scrape completes
  • if the scrape fails after extra pages were charged, those charges are reversed
TikTok currently returns about 15 videos per page, but that is an implementation detail and may change.

​
Tips for Large Profiles

  • use after_date to avoid crawling older history you do not need
  • use max_posts to cap the result size
  • prefer download_url after completion if you expect a large result set
  • poll the result endpoint while the task is processing instead of resubmitting the same scrape

​
Common Errors

  • request_body_required: the JSON body was missing
  • missing_parameter: profile_url was not sent
  • invalid_url: the submitted profile_url is malformed
  • invalid_parameter: one of the filters is malformed
The OpenAPI spec no longer lists unsupported_platform for this endpoint.

​
Next Step

After you receive the task_id, poll the result endpoint. You can use either the returned task_id or the check_status_url value:

Authorizations

​
X-API-Key
string
header
required

API key authentication. Include your VidNavigator API key in the X-API-Key header.

Body

application/json
​
profile_url
string<uri>
required

Public TikTok profile URL (e.g. https://www.tiktok.com/@username).

Example:

"https://www.tiktok.com/@tiktok"

​
max_posts
integer

Maximum number of matching videos to return. The scraper stops paginating once this is reached.

Required range: x >= 1
Example:

100

​
after_date
string

Only include videos uploaded on or after this date. Format: YYYYMMDD. Causes the scraper to stop paginating when it encounters videos older than this date.

Example:

"20240101"

​
before_date
string

Only include videos uploaded on or before this date. Format: YYYYMMDD.

Example:

"20241231"

​
min_likes
integer

Only include videos with at least this many likes.

Required range: x >= 0
​
max_likes
integer

Only include videos with at most this many likes.

Required range: x >= 0

Response

Task accepted and queued for background scraping.

​
status
enum<string>
Available options:
success
​
data
object