> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vidnavigator.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Submit TikTok Profile Scrape
> Start an asynchronous TikTok profile scrape and return a `task_id` immediately.
The scrape runs in the background with shallow extraction so it can stop early when filters are satisfied. Results are retained for 1 hour and, when cloud storage 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.
**Usage disclosure:** This endpoint does NOT accept `include_usage`. Because billing happens in the background worker after the 202 response is sent, there is nothing to disclose at submit time. Pass `include_usage=true` on `GET /tiktok/profile/{task_id}` instead — the GET endpoint replays the final charges once `task_status=completed`.
Use `GET /tiktok/profile/{task_id}` to poll status and retrieve paginated results, or follow `download_url` for the complete JSON.
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}`](/api-reference/endpoint/tiktok-profile-result) 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`.
| 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
```bash cURL theme={null}
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
}'
```
```python Python theme={null}
import requests
response = requests.post(
"https://api.vidnavigator.com/v1/tiktok/profile",
headers={
"X-API-Key": "YOUR_API_KEY",
"Content-Type": "application/json",
},
json={
"profile_url": "https://www.tiktok.com/@tiktok",
"max_posts": 50,
"after_datetime": "2024-01-01T00:00:00Z",
"min_likes": 10000,
},
)
print(response.json())
```
```javascript JavaScript theme={null}
const response = await fetch('https://api.vidnavigator.com/v1/tiktok/profile', {
method: 'POST',
headers: {
'X-API-Key': 'YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
profile_url: 'https://www.tiktok.com/@tiktok',
max_posts: 50,
after_datetime: '2024-01-01T00:00:00Z',
min_likes: 10000
})
});
const result = await response.json();
```
## Success Response
The endpoint returns `202 Accepted` because the scrape runs in the background.
```json theme={null}
{
"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](/api-reference/endpoint/tiktok-profile-result)
## OpenAPI
````yaml POST /tiktok/profile
openapi: 3.0.3
info:
title: VidNavigator Developer API
description: >-
The VidNavigator Developer API provides programmatic access to video
analysis, transcription, and search capabilities.
## Authentication
All endpoints require API key authentication via the `X-API-Key` header:
```
X-API-Key: YOUR_API_KEY
```
## Rate Limits
Check the documentation for the rate limits for each endpoint.
## Error Handling
The API uses standard HTTP status codes and returns error responses in JSON
format:
```json
{
"status": "error",
"error": "error_type",
"message": "Human readable error message"
}
```
version: 1.0.0
contact:
name: VidNavigator Support
url: https://vidnavigator.com/support
email: support@vidnavigator.com
license:
name: Proprietary
url: https://vidnavigator.com/terms
servers:
- url: https://api.vidnavigator.com/v1
description: Production server
security:
- ApiKeyAuth: []
tags:
- name: Transcripts
description: Extract transcripts from online videos
- name: TikTok
description: Scrape TikTok profile metadata and per-video stats
- name: Files
description: Manage uploaded audio/video files
- name: Analysis
description: AI-powered content analysis
- name: Extraction
description: >-
Extract structured data from video and file transcripts using custom
schemas
- name: Namespaces
description: Organize uploaded files into namespaces (folders)
- name: Search
description: Search videos and files using AI
- name: System
description: System health and information
- name: Tweet Analysis
description: Extract structured claims and metadata from X/Twitter tweets
paths:
/tiktok/profile:
post:
tags:
- TikTok
summary: Submit a TikTok profile scrape (async)
description: >-
Start an asynchronous TikTok profile scrape and return a `task_id`
immediately.
The scrape runs in the background with shallow extraction so it can stop
early when filters are satisfied. Results are retained for 1 hour and,
when cloud storage 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.
**Usage disclosure:** This endpoint does NOT accept `include_usage`.
Because billing happens in the background worker after the 202 response
is sent, there is nothing to disclose at submit time. Pass
`include_usage=true` on `GET /tiktok/profile/{task_id}` instead — the
GET endpoint replays the final charges once `task_status=completed`.
Use `GET /tiktok/profile/{task_id}` to poll status and retrieve
paginated results, or follow `download_url` for the complete JSON.
operationId: submitTikTokProfileScrape
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- profile_url
properties:
profile_url:
type: string
format: uri
description: >-
Public TikTok profile URL (e.g.
https://www.tiktok.com/@username).
example: https://www.tiktok.com/@tiktok
max_posts:
type: integer
minimum: 1
description: >-
Maximum number of matching videos to return. The scraper
stops paginating once this is reached.
example: 100
after_datetime:
type: string
description: >-
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:
type: string
description: >-
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:
type: integer
minimum: 0
description: Only include videos with at least this many likes.
max_likes:
type: integer
minimum: 0
description: Only include videos with at most this many likes.
responses:
'202':
description: Task accepted and queued for background scraping.
content:
application/json:
schema:
type: object
properties:
status:
type: string
enum:
- success
data:
type: object
properties:
task_id:
type: string
task_status:
type: string
enum:
- processing
profile_url:
type: string
format: uri
expires_at:
type: string
format: date-time
check_status_url:
type: string
description: Relative URL to poll for status and results.
example: >-
/v1/tiktok/profile/550e8400-e29b-41d4-a716-446655440000
message:
type: string
'400':
description: >-
Invalid request (missing or malformed `profile_url`, bad filter
values, non-TikTok URL).
content:
application/json:
schema:
type: object
properties:
status:
type: string
enum:
- error
error:
type: string
enum:
- request_body_required
- missing_parameter
- invalid_url
- invalid_parameter
message:
type: string
'402':
$ref: '#/components/responses/PaymentRequired'
'500':
$ref: '#/components/responses/InternalServerError'
components:
responses:
PaymentRequired:
description: Usage limit exceeded - upgrade required
content:
application/json:
schema:
type: object
properties:
status:
type: string
enum:
- error
error:
type: string
enum:
- limit_exceeded
message:
type: string
InternalServerError:
description: Internal server error
content:
application/json:
schema:
type: object
properties:
status:
type: string
enum:
- error
error:
type: string
enum:
- internal_server_error
message:
type: string
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: X-API-Key
description: >-
API key authentication. Include your VidNavigator API key in the
X-API-Key header.
````