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_datetime": "2024-01-01T00:00:00Z",
  "before_datetime": "2024-12-31",
  "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>"
  }
}

Online media

Submit TikTok Profile Scrape

Start an asynchronous TikTok profile scrape and return a task_id immediately.

The scrape runs in the background using a lazy yt-dlp generator with shallow extraction so it can stop early when filters are satisfied. Results are persisted in MongoDB (auto-deleted after 1 hour) and, when GCS is configured, also uploaded as a single JSON file accessible through download_url.

Billing: Each TikTok API page fetched is billed as one standard request. One page is pre-charged when the task is accepted; remaining pages are reconciled when the scrape completes. If the scrape fails after charging additional pages, all charged pages are reversed. TikTok currently returns ~15 videos per page; this is an internal estimate and may change.

Filters: All filters are applied as the scraper iterates. max_posts and after_datetime allow the scraper to stop fetching new pages early; the other filters reduce result size but do not stop pagination.

Use GET /tiktok/profile/{task_id} to poll status and retrieve paginated results, or follow download_url for the complete JSON.

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_datetime": "2024-01-01T00:00:00Z",
  "before_datetime": "2024-12-31",
  "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

Send POST /tiktok/profile with a public TikTok profile_url and optional filters.
The API accepts the task and returns a task_id with task_status: "processing".
Poll GET /tiktok/profile/{task_id} until the task is completed or failed.
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.

Field	Type	Description
`profile_url`	string	Public TikTok profile URL, such as `https://www.tiktok.com/@username`
`max_posts`	integer	Maximum number of matching videos to return
`after_datetime`	string	Include only videos published on or after this boundary. Accepts `YYYY-MM-DD` or an ISO datetime with timezone, such as `2024-01-01T00:00:00Z`.
`before_datetime`	string	Include only videos published on or before this boundary. Accepts `YYYY-MM-DD` or an ISO datetime with timezone, such as `2024-12-31T23:59:59+02:00`.
`min_likes`	integer	Include only videos with at least this many likes
`max_likes`	integer	Include only videos with at most this many likes

max_posts and after_datetime 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_datetime": "2024-01-01T00:00:00Z",
    "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_datetime 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:

Get TikTok profile scrape result

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_datetime

string

Only include videos published on or after this boundary. Accepts either YYYY-MM-DD or an ISO datetime with timezone (e.g. 2024-01-01T00:00:00Z). Filtering uses per-video timestamp when available (UTC), with upload-date fallback otherwise.

Example:

"2024-01-01T00:00:00Z"

before_datetime

string

Only include videos published on or before this boundary. Accepts either YYYY-MM-DD or an ISO datetime with timezone (e.g. 2024-12-31T23:59:59+02:00). Filtering uses per-video timestamp when available (UTC), with upload-date fallback otherwise.

Example:

"2024-12-31"

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

Show child attributes

Tweet Claim Analysis Get TikTok Profile Scrape Result

API Documentation

Online media

Local Files

System

Submit TikTok Profile Scrape

Overview

How the Async Flow Works

Filters You Can Apply

What You Get Back Immediately

Example Request

Success Response

Billing Notes

Tips for Large Profiles

Common Errors

Next Step

Authorizations

Body

Response

API Documentation

Online media

Local Files

System

Documentation Index

​Overview

​How the Async Flow Works

​Filters You Can Apply

​What You Get Back Immediately

​Example Request

​Success Response

​Billing Notes

​Tips for Large Profiles

​Common Errors

​Next Step

Authorizations

Body

Response

Overview

How the Async Flow Works

Filters You Can Apply

What You Get Back Immediately

Example Request

Success Response

Billing Notes

Tips for Large Profiles

Common Errors

Next Step