curl --request POST \
--url https://api.vidnavigator.com/v1/tiktok/search \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"query": "ai tools",
"max_results": 0,
"parallel_search_slices": 2,
"sort_by": "newest",
"published_within": "this_week",
"after_datetime": "<string>",
"before_datetime": "<string>",
"min_likes": 1,
"max_likes": 1,
"min_views": 1,
"max_views": 1,
"webhook_url": "https://example.com/hooks/vidnavigator"
}
'import requests
url = "https://api.vidnavigator.com/v1/tiktok/search"
payload = {
"query": "ai tools",
"max_results": 0,
"parallel_search_slices": 2,
"sort_by": "newest",
"published_within": "this_week",
"after_datetime": "<string>",
"before_datetime": "<string>",
"min_likes": 1,
"max_likes": 1,
"min_views": 1,
"max_views": 1,
"webhook_url": "https://example.com/hooks/vidnavigator"
}
headers = {
"X-API-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
query: 'ai tools',
max_results: 0,
parallel_search_slices: 2,
sort_by: 'newest',
published_within: 'this_week',
after_datetime: '<string>',
before_datetime: '<string>',
min_likes: 1,
max_likes: 1,
min_views: 1,
max_views: 1,
webhook_url: 'https://example.com/hooks/vidnavigator'
})
};
fetch('https://api.vidnavigator.com/v1/tiktok/search', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.vidnavigator.com/v1/tiktok/search",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'query' => 'ai tools',
'max_results' => 0,
'parallel_search_slices' => 2,
'sort_by' => 'newest',
'published_within' => 'this_week',
'after_datetime' => '<string>',
'before_datetime' => '<string>',
'min_likes' => 1,
'max_likes' => 1,
'min_views' => 1,
'max_views' => 1,
'webhook_url' => 'https://example.com/hooks/vidnavigator'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-API-Key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.vidnavigator.com/v1/tiktok/search"
payload := strings.NewReader("{\n \"query\": \"ai tools\",\n \"max_results\": 0,\n \"parallel_search_slices\": 2,\n \"sort_by\": \"newest\",\n \"published_within\": \"this_week\",\n \"after_datetime\": \"<string>\",\n \"before_datetime\": \"<string>\",\n \"min_likes\": 1,\n \"max_likes\": 1,\n \"min_views\": 1,\n \"max_views\": 1,\n \"webhook_url\": \"https://example.com/hooks/vidnavigator\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-API-Key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.vidnavigator.com/v1/tiktok/search")
.header("X-API-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"query\": \"ai tools\",\n \"max_results\": 0,\n \"parallel_search_slices\": 2,\n \"sort_by\": \"newest\",\n \"published_within\": \"this_week\",\n \"after_datetime\": \"<string>\",\n \"before_datetime\": \"<string>\",\n \"min_likes\": 1,\n \"max_likes\": 1,\n \"min_views\": 1,\n \"max_views\": 1,\n \"webhook_url\": \"https://example.com/hooks/vidnavigator\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.vidnavigator.com/v1/tiktok/search")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"query\": \"ai tools\",\n \"max_results\": 0,\n \"parallel_search_slices\": 2,\n \"sort_by\": \"newest\",\n \"published_within\": \"this_week\",\n \"after_datetime\": \"<string>\",\n \"before_datetime\": \"<string>\",\n \"min_likes\": 1,\n \"max_likes\": 1,\n \"min_views\": 1,\n \"max_views\": 1,\n \"webhook_url\": \"https://example.com/hooks/vidnavigator\"\n}"
response = http.request(request)
puts response.read_body{
"status": "success",
"data": {
"task_id": "<string>",
"task_status": "processing",
"query": "<string>",
"max_results": 123,
"parallel_search_slices": 2,
"filters": {},
"expires_at": "2023-11-07T05:31:56Z",
"check_status_url": "/v1/tiktok/search/550e8400-e29b-41d4-a716-446655440000",
"message": "<string>",
"webhook_url": "<string>"
}
}{
"status": "error",
"error": "<string>",
"message": "<string>"
}{
"status": "error",
"error": "metadata_fetch_failed",
"message": "<string>"
}TikTok Keyword Search
Start an asynchronous TikTok keyword search task and return a task_id immediately. Poll GET /tiktok/search/{task_id} for cursor-paginated results. Results are retained for ~1 hour.
Results are returned sorted by published_at descending (newest first) across pagination, full retrieval, and the signed download_url payload, unless sort_by is set, in which case that order is kept.
parallel_search_slices billing: by default (1), the search runs a single paginated query chain and is naturally capped at roughly 115-140 items by TikTok. Setting parallel_search_slices to 2..4 runs that many concurrent chains in parallel and dedups by video id, lifting the effective ceiling. Cost scales linearly: each additional slice consumes up to ~1x the residential pages of a single search, so an N-slice request bills up to Nx the residential pages. Extra slices add the most on searches without a date window; with published_within set, every slice searches the same window and can return largely the same videos. parallel_search_slices is not a time filter — use published_within, after_datetime or before_datetime for time windows.
Usage disclosure: This endpoint does NOT accept include_usage. Billing happens in the background worker after the 202 response is sent, so there is nothing to disclose at submit time. Pass include_usage=true on GET /tiktok/search/{task_id} instead — the GET endpoint replays the final charges once task_status=completed.
curl --request POST \
--url https://api.vidnavigator.com/v1/tiktok/search \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"query": "ai tools",
"max_results": 0,
"parallel_search_slices": 2,
"sort_by": "newest",
"published_within": "this_week",
"after_datetime": "<string>",
"before_datetime": "<string>",
"min_likes": 1,
"max_likes": 1,
"min_views": 1,
"max_views": 1,
"webhook_url": "https://example.com/hooks/vidnavigator"
}
'import requests
url = "https://api.vidnavigator.com/v1/tiktok/search"
payload = {
"query": "ai tools",
"max_results": 0,
"parallel_search_slices": 2,
"sort_by": "newest",
"published_within": "this_week",
"after_datetime": "<string>",
"before_datetime": "<string>",
"min_likes": 1,
"max_likes": 1,
"min_views": 1,
"max_views": 1,
"webhook_url": "https://example.com/hooks/vidnavigator"
}
headers = {
"X-API-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
query: 'ai tools',
max_results: 0,
parallel_search_slices: 2,
sort_by: 'newest',
published_within: 'this_week',
after_datetime: '<string>',
before_datetime: '<string>',
min_likes: 1,
max_likes: 1,
min_views: 1,
max_views: 1,
webhook_url: 'https://example.com/hooks/vidnavigator'
})
};
fetch('https://api.vidnavigator.com/v1/tiktok/search', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.vidnavigator.com/v1/tiktok/search",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'query' => 'ai tools',
'max_results' => 0,
'parallel_search_slices' => 2,
'sort_by' => 'newest',
'published_within' => 'this_week',
'after_datetime' => '<string>',
'before_datetime' => '<string>',
'min_likes' => 1,
'max_likes' => 1,
'min_views' => 1,
'max_views' => 1,
'webhook_url' => 'https://example.com/hooks/vidnavigator'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-API-Key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.vidnavigator.com/v1/tiktok/search"
payload := strings.NewReader("{\n \"query\": \"ai tools\",\n \"max_results\": 0,\n \"parallel_search_slices\": 2,\n \"sort_by\": \"newest\",\n \"published_within\": \"this_week\",\n \"after_datetime\": \"<string>\",\n \"before_datetime\": \"<string>\",\n \"min_likes\": 1,\n \"max_likes\": 1,\n \"min_views\": 1,\n \"max_views\": 1,\n \"webhook_url\": \"https://example.com/hooks/vidnavigator\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-API-Key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.vidnavigator.com/v1/tiktok/search")
.header("X-API-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"query\": \"ai tools\",\n \"max_results\": 0,\n \"parallel_search_slices\": 2,\n \"sort_by\": \"newest\",\n \"published_within\": \"this_week\",\n \"after_datetime\": \"<string>\",\n \"before_datetime\": \"<string>\",\n \"min_likes\": 1,\n \"max_likes\": 1,\n \"min_views\": 1,\n \"max_views\": 1,\n \"webhook_url\": \"https://example.com/hooks/vidnavigator\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.vidnavigator.com/v1/tiktok/search")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"query\": \"ai tools\",\n \"max_results\": 0,\n \"parallel_search_slices\": 2,\n \"sort_by\": \"newest\",\n \"published_within\": \"this_week\",\n \"after_datetime\": \"<string>\",\n \"before_datetime\": \"<string>\",\n \"min_likes\": 1,\n \"max_likes\": 1,\n \"min_views\": 1,\n \"max_views\": 1,\n \"webhook_url\": \"https://example.com/hooks/vidnavigator\"\n}"
response = http.request(request)
puts response.read_body{
"status": "success",
"data": {
"task_id": "<string>",
"task_status": "processing",
"query": "<string>",
"max_results": 123,
"parallel_search_slices": 2,
"filters": {},
"expires_at": "2023-11-07T05:31:56Z",
"check_status_url": "/v1/tiktok/search/550e8400-e29b-41d4-a716-446655440000",
"message": "<string>",
"webhook_url": "<string>"
}
}{
"status": "error",
"error": "<string>",
"message": "<string>"
}{
"status": "error",
"error": "metadata_fetch_failed",
"message": "<string>"
}task_id back immediately.
Overview
This endpoint runs an actual keyword search across TikTok (not a single profile) and returns multiple matching videos. It is asynchronous: the search runs in a background worker, and you pollGET /tiktok/search/{task_id} for cursor-paginated results. Results are retained for ~1 hour.
Results are returned sorted by published_at descending (newest first) across pagination, full retrieval, and the signed download_url payload — unless you set sort_by, in which case that order is kept.
Billing
Charges happen in the background worker and are disclosed on the polling endpoint (see below), not here.- Billing is
pages_fetched × residential_request. Nosearch_requestis billed for TikTok keyword search. parallel_search_slicesscales the cost linearly. By default (1) the search runs a single paginated query chain, naturally capped at roughly 115–140 items by TikTok. Setting it to2..4runs that many concurrent chains and dedups by video id, lifting the ceiling — but an N-slice request bills up to N× the residential pages of a single search. Extra slices help most on searches without a date window: withpublished_withinset, every slice searches the same window and can return largely the same videos.
include_usage. Because billing happens after the 202 response is sent, there is nothing to disclose at submit time. Pass include_usage=true on GET /tiktok/search/{task_id} instead — it replays the final charges once task_status=completed.Request Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
query | string | Yes | Keyword phrase to search on TikTok (min length 2). |
max_results | integer | No | Upper bound on results the task will try to collect. 0 (default) or omitted means unlimited — pagination stops only when TikTok has no more results or the page cap is reached (~115–140 items per slice: ~5 pages of ~30 items). No hard server-side cap is enforced; you are billed per residential page actually fetched. |
parallel_search_slices | integer | No | How many concurrent paginated query chains to run and dedup (1–4, default 1). Higher values lift the result ceiling at up to ~N× the residential pages of a single search. With published_within set, keep 1 unless you have measured a gain. Not a time filter — use published_within, after_datetime or before_datetime for time windows. |
sort_by | string | No | Sort order applied by TikTok itself (same as the app’s search Filters): relevance, most_liked or newest. See Sorting and date windows. |
published_within | string | No | Publication window applied by TikTok itself: all, past_24_hours, this_week, this_month, last_3_months or last_6_months. Windows are rolling (this_week = the last 7 days). |
after_datetime | string | No | Only include videos published on or after this boundary. Accepts YYYY-MM-DD or an ISO datetime with timezone. Unless sort_by or published_within is set, it also makes the search run newest first and stop once it passes this boundary. |
before_datetime | string | No | Only include videos published on or before this boundary. Accepts YYYY-MM-DD or an ISO datetime with timezone. |
min_likes | integer | No | Only include videos with at least this many likes. |
max_likes | integer | No | Only include videos with at most this many likes. |
min_views | integer | No | Only include videos with at least this many views. |
max_views | integer | No | Only include videos with at most this many views. |
webhook_url | string | No | Where to POST a notification when the task finishes. Overrides the account default set in Studio → API; pass "" to opt this task out of the default. Must be a public https URL. The event carries stats and points you to check_status_url for the results. See Webhooks. |
Sorting and date windows
sort_by and published_within are applied by TikTok itself, before VidNavigator’s own filters (after_datetime, min_likes, …). Using them well returns more matching videos per billed page.
sort_by | Order |
|---|---|
relevance | TikTok’s own ranking |
most_liked | By like count |
newest | By publish date, newest first |
sort_by is omitted, results are returned newest first, and the search is ordered to fit your filters:
after_datetimeorbefore_datetimeset → the search runs newest first and stops once it passesafter_datetime- only
min_likesormin_viewsset → the search runs most liked first
published_within is omitted and after_datetime is more than 24 hours ago, the smallest window that covers after_datetime is selected automatically. The window actually used is reported in stats.published_within on the result endpoint.
{
"query": "ai tools",
"sort_by": "most_liked",
"published_within": "this_week",
"min_views": 10000
}
Example Usage
curl -X POST "https://api.vidnavigator.com/v1/tiktok/search" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"query": "ai tools",
"parallel_search_slices": 2,
"after_datetime": "2024-01-01T00:00:00Z",
"min_likes": 1000
}'
import requests
url = "https://api.vidnavigator.com/v1/tiktok/search"
headers = {
"X-API-Key": "YOUR_API_KEY",
"Content-Type": "application/json"
}
data = {
"query": "ai tools",
"parallel_search_slices": 2,
"after_datetime": "2024-01-01T00:00:00Z",
"min_likes": 1000
}
response = requests.post(url, headers=headers, json=data)
task = response.json()
print("Task ID:", task["data"]["task_id"])
const response = await fetch('https://api.vidnavigator.com/v1/tiktok/search', {
method: 'POST',
headers: {
'X-API-Key': 'YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
query: 'ai tools',
parallel_search_slices: 2,
after_datetime: '2024-01-01T00:00:00Z',
min_likes: 1000
})
});
const task = await response.json();
console.log('Task ID:', task.data.task_id);
Success Response (202 Accepted)
{
"status": "success",
"data": {
"task_id": "550e8400-e29b-41d4-a716-446655440000",
"task_status": "processing",
"query": "ai tools",
"max_results": 0,
"parallel_search_slices": 2,
"filters": {
"sort_by": null,
"published_within": null,
"after_datetime": "2024-01-01T00:00:00Z",
"before_datetime": null,
"min_likes": 1000,
"max_likes": null,
"min_views": null,
"max_views": null
},
"expires_at": "2026-04-26T13:00:00Z",
"check_status_url": "/v1/tiktok/search/550e8400-e29b-41d4-a716-446655440000",
"webhook_url": null,
"message": "TikTok search task accepted and queued."
}
}
Get the result
GET /tiktok/search/{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.
Request Parameters
| Parameter | In | Required | Description |
|---|---|---|---|
task_id | path | Yes | Task ID returned by POST /tiktok/search |
cursor | query | No | Opaque pagination cursor from a previous response |
limit | query | No | Maximum number of items to return, between 1 and 500. Default is 50. |
include_usage | query | No | When true and task_status=completed, attach a usage block describing the charges the background worker recorded (pages_fetched × residential_request; no search_request for TikTok keyword search). |
Usage Disclosure
Because billing happens in the background worker, the submit endpoint cannot disclose usage. Instead, passinclude_usage=true here:
- Returned only when
task_status=completed(processing tasks haven’t finished billing; failed tasks have all charges refunded). - Charges are
pages_fetched × residential_request. Nosearch_requestis billed for TikTok keyword search.
Polling Lifecycle
Thetask_status field will be one of:
processing: the search is still runningcompleted: the search finished and results are readyfailed: the search ended with an error (all charges refunded)
results will be empty and download_url will usually be null.
Example Requests
curl "https://api.vidnavigator.com/v1/tiktok/search/tt_search_abc123?limit=25&include_usage=true" \
-H "X-API-Key: YOUR_API_KEY"
import requests
response = requests.get(
"https://api.vidnavigator.com/v1/tiktok/search/tt_search_abc123",
headers={"X-API-Key": "YOUR_API_KEY"},
params={"limit": 25, "include_usage": "true"},
)
print(response.json())
const response = await fetch(
'https://api.vidnavigator.com/v1/tiktok/search/tt_search_abc123?limit=25&include_usage=true',
{
headers: {
'X-API-Key': 'YOUR_API_KEY'
}
}
);
const result = await response.json();
Example Completed Response
{
"status": "success",
"data": {
"task_id": "tt_search_abc123",
"task_status": "completed",
"query": "ai tools",
"parallel_search_slices": 2,
"filters": {
"sort_by": null,
"published_within": null,
"after_datetime": "2024-01-01T00:00:00Z",
"before_datetime": null,
"min_likes": 1000,
"max_likes": null,
"min_views": null,
"max_views": null
},
"stats": {
"pages_fetched": 18,
"results_count": 172,
"next_search_cursor": null,
"sort_by": "relevance",
"published_within": "all"
},
"results": [
{
"id": "7351234567890123456",
"item_type": 1,
"description": "Top AI tools you should try",
"timestamp": 1712345678,
"published_at": "2024-04-05T19:34:38Z",
"author": {
"id": "6789",
"unique_id": "creator",
"nickname": "Creator Name",
"sec_uid": "MS4wLjAB..."
},
"stats": {
"views": 250000,
"likes": 22000,
"comments": 950,
"shares": 120,
"collects": 340
},
"music": {
"id": "1122",
"title": "Original sound",
"author_name": "creator",
"duration": 30
},
"duration": 28,
"hashtags": ["ai", "tools", "productivity"],
"url": "https://www.tiktok.com/@creator/video/7351234567890123456"
}
],
"pagination": {
"limit": 25,
"offset": 0,
"total_items": 172,
"has_next": true,
"has_prev": false,
"next_cursor": "eyJvZmZzZXQiOjI1fQ==",
"prev_cursor": null
},
"download_url": "https://storage.googleapis.com/bucket/api/tiktok_searches/user/task.json?...",
"error_message": null,
"error": null,
"webhook": null,
"created_at": "2026-04-26T12:00:00Z",
"completed_at": "2026-04-26T12:01:40Z",
"expires_at": "2026-04-26T13:00:00Z"
},
"usage": {
"charges": [
{ "service_type": "residential_request", "quantity": 18, "credits": 0.09 }
],
"total_credits": 0.09
}
}
usage block appears only when include_usage=true and task_status=completed.Understanding the Response
stats
pages_fetched: number of TikTok pages fetched (this is what you are billed for, asresidential_request)results_count: total normalized items collectednext_search_cursor: internal upstream cursor, ornullwhen exhaustedsort_by: sort order the search ran with (relevancewhensort_bywas omitted)published_within: date window the search ran with — shows the window chosen fromafter_datetimewhenpublished_withinwas omitted;allmeans no window
results
Each item is a normalized TikTok video with id, description, timestamp, published_at (UTC ISO 8601), author, stats (views/likes/comments/shares/collects), music, duration, hashtags, and url. Items are sorted by published_at descending (items without a timestamp go last), unless sort_by was set, in which case TikTok’s order is kept.
download_url
When present, a short-lived signed URL pointing to the full search result as one JSON file (same shape as the paginated results, but unsliced). null when the task hasn’t finished or the full result wasn’t archived — paginate through results 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 request (e.g. bad cursor)404: task does not exist, expired, or does not belong to the current user
Tips
- poll every few seconds while
task_statusisprocessing - switch to
download_urlfor large completed jobs - tasks expire after about 1 hour — use
expires_atto avoid polling expired tasks - call the endpoint again later if you need a freshly minted
download_url
Authorizations
API key authentication. Include your VidNavigator API key in the X-API-Key header.
Body
Keyword phrase to search on TikTok.
2"ai tools"
Optional upper bound on results the background task will try to collect. 0 (the default) or omitted means unlimited — pagination only stops when TikTok has no more results or the page cap is reached. With parallel_search_slices=1 that naturally yields ~115-140 items (TikTok serves ~5 pages of ~30 items per chain); with parallel_search_slices=4 up to ~480 unique items. A positive integer caps the merged result count. No hard server-side cap is enforced — a caller asking for 3000 will be billed per residential page actually fetched (~5 pages per slice naturally) and receive whatever TikTok delivers.
x >= 0How many concurrent paginated query chains to run and dedup by video id. 1 (the default) is a single chain naturally capped at roughly 115-140 items. 2..4 runs that many additional chains in parallel, lifting the effective ceiling at the cost of up to ~Nx the residential pages of a single search. Diminishing returns: 2 slices yield ~+43% unique items, 3 slices ~+22%, 4 slices ~+13% on a representative query without a date window, so 4 already saturates TikTok's natural ~480-item dedup ceiling for most queries. With published_within set, every slice searches the same window and extra slices can return largely the same videos, so keep 1 unless you have measured a gain. parallel_search_slices is not a time filter — use published_within, after_datetime or before_datetime for time windows.
1 <= x <= 42
Sort order applied by TikTok itself (the same control as the app's search Filters sheet). relevance returns results in TikTok's ranking, most_liked by like count, newest by publish date, newest first. When omitted, results are returned newest first, and the search itself is ordered to fit your filters: newest first when after_datetime or before_datetime is set (stopping once it passes after_datetime), most liked first when only min_likes or min_views is set. That returns more matching videos per billed page.
relevance, most_liked, newest "newest"
Publication window applied by TikTok itself. Windows are rolling (this_week = the last 7 days). When omitted and after_datetime is more than 24 hours ago, the smallest window that covers after_datetime is selected automatically.
all, past_24_hours, this_week, this_month, last_3_months, last_6_months "this_week"
Only include videos published on or after this boundary. Accepts YYYY-MM-DD or ISO datetime with timezone. Unless sort_by or published_within is set, it also makes the search run newest first and stop once it passes this boundary, so more results in range come back per billed page.
Only include videos published on or before this boundary. Accepts YYYY-MM-DD or ISO datetime with timezone.
x >= 0x >= 0x >= 0x >= 0Where 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
"https://example.com/hooks/vidnavigator"

