Skip to main content
POST
Submit a TikTok profile scrape (async)
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.
The TikTok webhook event is a notification, not the payload: a scrape can hold thousands of videos, so the event carries stats and tells you to read the results from check_status_url.
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
  • webhook_url: the URL the completion notification will be POSTed to, or null
  • message confirming the job was accepted

Example Request

Success Response

The endpoint returns 202 Accepted because the scrape runs in the background.

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.

Get the result

GET /tiktok/profile/{task_id} — poll this endpoint with the task_id (or the check_status_url) returned above, or wait for the webhook notification. Polling does not consume credits.
The playground above only covers the submit request. Call the result endpoint with cURL or your HTTP client.

Request Parameters

How Pagination Works

Pagination is cursor-based, but the cursor encodes an absolute offset. That means you can safely change limit between requests without skipping or duplicating videos. Typical flow:
  1. Call the endpoint with no cursor.
  2. Read data.pagination.next_cursor.
  3. Pass that value back as the next request’s cursor.
  4. Stop when has_next is false.

Polling Lifecycle

The task_status field will be one of:
  • processing: the scrape is still running
  • completed: the scrape finished and results are ready
  • failed: the scrape ended with an error
While the task is still processing:
  • profile may be null
  • videos will be empty
  • download_url will usually be null
Once completed:
  • videos contains a cursor-paginated page of matching posts
  • pagination tells you whether more pages exist
  • download_url may contain a temporary signed URL for the full JSON result

Example Requests

Fetch the Next Page

cURL

Example Completed Response

Understanding the Response

profile

Contains profile-level metadata returned by the scraper, such as uploader information and follower counts when available.

stats

Helps you understand what happened during the scrape:
  • videos_scanned: total TikTok entries iterated before filtering
  • videos_matched: entries that passed your filters
  • pages_consumed: estimated number of TikTok API pages fetched during the scrape

videos

This is the current page of matched TikTok videos. Each item includes public metadata such as:
  • id
  • title
  • description
  • timestamp: Unix timestamp in seconds when the video was uploaded
  • published_at: UTC datetime string derived from timestamp, in ISO 8601 format with timezone
  • views
  • likes
  • comments
  • url

download_url

When present, this is a short-lived signed URL pointing to the full scrape result as one JSON file. It is useful for large profiles, browser downloads, and no-code integrations. If it is null, either:
  • the task has not finished yet, or
  • the full result wasn’t archived, and you should paginate through videos instead

error

Present when task_status is failed: an object with error (a code you can branch on), message and http_status. See Errors.
error_message is deprecated. It is kept for existing integrations, but new code should read error.error / error.message instead.

webhook

Delivery state of the task’s webhook notification (status, attempts, response_status, last_error, delivered_at), or null when no webhook applies.

Error Cases

  • 400 invalid_cursor: the supplied cursor is invalid
  • 404 task_not_found: task does not exist, expired, or does not belong to the current user

Tips

  • poll every few seconds while task_status is processing
  • switch to download_url for large completed jobs
  • do not assume tasks live forever; they expire after about 1 hour
  • call the endpoint again later if you need a freshly minted download_url
  • use the expires_at value to avoid polling a task after it has already expired

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
webhook_url
string<uri>

Where to POST the result when the task finishes. Overrides the account-level default configured in Studio → API; pass an empty string to opt this task out of that default. Must be a publicly reachable https URL. The event is a notification, not the payload: a scrape can hold thousands of videos, so it carries stats and tells you to read the result from check_status_url. See https://docs.vidnavigator.com/guides/webhooks

Example:

"https://example.com/hooks/vidnavigator"

Response

Task accepted and queued for background scraping.

status
enum<string>
Available options:
success
data
object