Searching TikTok

Overview

VidNavigator offers two ways to collect TikTok videos:

Profile Scrape

Walk a single creator’s account and return their videos, filtered by date and likes.

Keyword Search

Search across TikTok by keyword and return matching videos from many creators.

Both are asynchronous: you submit a task, get a task_id back immediately, then poll a GET endpoint until the task is completed. Results are retained for about 1 hour, and large result sets can be downloaded as a single JSON file via a temporary download_url.

The Python and JavaScript SDKs (v2.1.0) wrap the submit-and-poll flow in a single call. Each section below starts with the SDK version, followed by the raw HTTP workflow (cURL, Python requests, and fetch) if you’d rather call the API directly.

Prerequisites

A valid VidNavigator API key.
Optional: the SDK, version 2.1.0 (pip install vidnavigator==2.1.0 or npm install vidnavigator@2.1.0).

Billing

Both endpoints bill in the background worker, so usage is disclosed on the polling GET (pass include_usage=true there), not at submit time.

Endpoint	What you’re billed
Profile scrape (`/tiktok/profile`)	`standard_request` per TikTok page fetched (`residential_request` when a residential proxy is used).
Keyword search (`/tiktok/search`)	`residential_request` per page fetched (`pages_fetched × residential_request`). An N-slice search bills up to N× the pages. No `search_request`.

See Usage & Costs for credit conversions.

Searching a TikTok Profile

Send a public profile_url and optional filters. max_posts and after_datetime let the scraper stop paginating early.

With the SDK

One call submits the scrape, waits for it to finish, and returns the videos. In JavaScript you get every matching video (the SDK walks all pages); in Python you get the first page of limit videos plus the pagination cursor.

from vidnavigator import VidNavigatorClient

client = VidNavigatorClient()  # reads VIDNAVIGATOR_API_KEY

result = client.scrape_tiktok_profile(
    profile_url="https://www.tiktok.com/@tiktok",
    max_posts=50,
    after_datetime="2024-01-01",
    min_likes=10000,
    limit=50,  # size of the returned page
)

for video in result.data.videos or []:
    print(video.published_at, video.likes, video.url)  # published_at is a datetime

# Read the remaining pages, if any
task_id, pagination = result.data.task_id, result.data.pagination
while pagination and pagination.has_next:
    page = client.get_tiktok_profile_scrape(task_id, cursor=pagination.next_cursor, limit=50)
    for video in page.data.videos or []:
        print(video.published_at, video.likes, video.url)
    pagination = page.data.pagination

import { VidNavigatorClient } from 'vidnavigator';

const vn = new VidNavigatorClient({ apiKey: process.env.VIDNAVIGATOR_API_KEY });

const task = await vn.tiktokProfile({
  profile_url: 'https://www.tiktok.com/@tiktok',
  max_posts: 50,
  after_datetime: '2024-01-01',
  min_likes: 10000,
});

console.log(`Collected ${task.videos.length} videos`, task.stats);
for (const video of task.videos.slice(0, 5)) {
  console.log(video.published_at?.toISOString(), video.likes, video.url); // published_at is a Date
}

To start the scrape without waiting, use client.submit_tiktok_profile_scrape(...) (Python) or vn.tiktokProfile.submit(...) (JavaScript) and collect it later with job.result(). Both accept a webhook_url to be notified when the scrape finishes.

With raw HTTP

1. Submit the scrape

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
  }'

import requests

BASE = "https://api.vidnavigator.com/v1"
HEADERS = {"X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json"}

resp = requests.post(
    f"{BASE}/tiktok/profile",
    headers=HEADERS,
    json={
        "profile_url": "https://www.tiktok.com/@tiktok",
        "max_posts": 50,
        "after_datetime": "2024-01-01T00:00:00Z",
        "min_likes": 10000,
    },
)
task_id = resp.json()["data"]["task_id"]
print("Task ID:", task_id)

const BASE = "https://api.vidnavigator.com/v1";
const HEADERS = {
  "X-API-Key": "YOUR_API_KEY",
  "Content-Type": "application/json",
};

const submit = await fetch(`${BASE}/tiktok/profile`, {
  method: "POST",
  headers: HEADERS,
  body: JSON.stringify({
    profile_url: "https://www.tiktok.com/@tiktok",
    max_posts: 50,
    after_datetime: "2024-01-01T00:00:00Z",
    min_likes: 10000,
  }),
});
const { data } = await submit.json();
const taskId = data.task_id;
console.log("Task ID:", taskId);

2. Poll until completed and page through results

Poll GET /tiktok/profile/{task_id} while task_status is processing. Once completed, walk the pages using the next_cursor from data.pagination.

import time

def get_profile_page(task_id, cursor=None, limit=50):
    params = {"limit": limit}
    if cursor:
        params["cursor"] = cursor
    r = requests.get(f"{BASE}/tiktok/profile/{task_id}", headers=HEADERS, params=params)
    return r.json()["data"]

# Wait for completion
while True:
    data = get_profile_page(task_id, limit=1)
    if data["task_status"] != "processing":
        break
    time.sleep(3)

if data["task_status"] == "failed":
    raise RuntimeError((data.get("error") or {}).get("message", "scrape failed"))

# Page through all videos
videos, cursor = [], None
while True:
    page = get_profile_page(task_id, cursor=cursor, limit=100)
    videos.extend(page["videos"])
    pagination = page["pagination"]
    if not pagination["has_next"]:
        break
    cursor = pagination["next_cursor"]

print(f"Collected {len(videos)} videos")
for v in videos[:5]:
    print(v["published_at"], v["likes"], v["url"])

async function getProfilePage(taskId, { cursor, limit = 50, includeUsage = false } = {}) {
  const params = new URLSearchParams({ limit: String(limit) });
  if (cursor) params.set("cursor", cursor);
  if (includeUsage) params.set("include_usage", "true");
  const r = await fetch(`${BASE}/tiktok/profile/${taskId}?${params}`, { headers: HEADERS });
  return (await r.json()).data;
}

// Wait for completion
let status;
do {
  status = await getProfilePage(taskId, { limit: 1 });
  if (status.task_status === "processing") await new Promise((res) => setTimeout(res, 3000));
} while (status.task_status === "processing");

if (status.task_status === "failed") throw new Error(status.error?.message || "scrape failed");

// Page through all videos
const videos = [];
let cursor = null;
let hasNext = true;
while (hasNext) {
  const page = await getProfilePage(taskId, { cursor, limit: 100 });
  videos.push(...page.videos);
  hasNext = page.pagination.has_next;
  cursor = page.pagination.next_cursor;
}

console.log(`Collected ${videos.length} videos`);

For very large profiles, skip pagination and download the whole result at once: once the task is completed, data.download_url holds a short-lived signed URL to the full JSON. Call the GET endpoint again to mint a fresh URL if it expires.

Searching TikTok by Keyword

Keyword search returns videos across many creators, sorted by published_at (newest first) unless you set sort_by (relevance, most_liked, newest). Use published_within (past_24_hours, this_week, this_month, last_3_months, last_6_months) or after_datetime / before_datetime for time windows, and parallel_search_slices (1–4) to lift the result ceiling (~115–140 items per slice) — most useful on searches without a date window.

With the SDK

result = client.search_tiktok(
    query="ai tools",
    sort_by="most_liked",
    published_within="this_month",
    min_likes=1000,
    limit=50,
    include_usage=True,
)

stats = result.data.stats
print(f"{stats.results_count} results, sorted by {stats.sort_by} within {stats.published_within}")

for item in result.data.results or []:
    print(item.published_at, item.stats.likes if item.stats else None, item.url)

if result.usage:
    print("Credits charged:", result.usage.total_credits)

const task = await vn.tiktokSearch(
  {
    query: 'ai tools',
    sort_by: 'most_liked',
    published_within: 'this_month',
    min_likes: 1000,
  },
  { include_usage: true }
);

console.log(`${task.results.length} results, sorted by ${task.stats?.sort_by} within ${task.stats?.published_within}`);
for (const item of task.results.slice(0, 5)) {
  console.log(item.published_at?.toISOString(), item.stats?.likes, item.url);
}
if (task.usage) console.log('Credits charged:', task.usage.total_credits);

Python pages through further results with client.get_tiktok_search(task_id, cursor=...), exactly like the profile example. The JavaScript call already returns every result.

With raw HTTP

1. Submit the search

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
  }'

resp = requests.post(
    f"{BASE}/tiktok/search",
    headers=HEADERS,
    json={
        "query": "ai tools",
        "parallel_search_slices": 2,
        "after_datetime": "2024-01-01T00:00:00Z",
        "min_likes": 1000,
    },
)
task_id = resp.json()["data"]["task_id"]
print("Task ID:", task_id)

const submit = await fetch(`${BASE}/tiktok/search`, {
  method: "POST",
  headers: HEADERS,
  body: JSON.stringify({
    query: "ai tools",
    parallel_search_slices: 2,
    after_datetime: "2024-01-01T00:00:00Z",
    min_likes: 1000,
  }),
});
const taskId = (await submit.json()).data.task_id;
console.log("Task ID:", taskId);

2. Poll, paginate, and read usage

The polling flow is identical to the profile scrape — just swap the path to /tiktok/search/{task_id} and read data.results instead of data.videos. Pass include_usage=true once the task is completed to see what was billed.

import time

def get_search_page(task_id, cursor=None, limit=50, include_usage=False):
    params = {"limit": limit}
    if cursor:
        params["cursor"] = cursor
    if include_usage:
        params["include_usage"] = "true"
    r = requests.get(f"{BASE}/tiktok/search/{task_id}", headers=HEADERS, params=params)
    return r.json()

# Wait for completion
while True:
    body = get_search_page(task_id, limit=1)
    if body["data"]["task_status"] != "processing":
        break
    time.sleep(3)

# First completed page, with usage disclosure
body = get_search_page(task_id, limit=50, include_usage=True)
data = body["data"]
print(f"{data['stats']['results_count']} results across {data['stats']['pages_fetched']} pages")

for item in data["results"][:5]:
    print(item["published_at"], item["stats"]["likes"], item["url"])

# Usage is at the top level of the response
if "usage" in body:
    print("Credits charged:", body["usage"]["total_credits"])

async function getSearchPage(taskId, { cursor, limit = 50, includeUsage = false } = {}) {
  const params = new URLSearchParams({ limit: String(limit) });
  if (cursor) params.set("cursor", cursor);
  if (includeUsage) params.set("include_usage", "true");
  const r = await fetch(`${BASE}/tiktok/search/${taskId}?${params}`, { headers: HEADERS });
  return await r.json();
}

// Wait for completion
let body;
do {
  body = await getSearchPage(taskId, { limit: 1 });
  if (body.data.task_status === "processing") await new Promise((res) => setTimeout(res, 3000));
} while (body.data.task_status === "processing");

// First completed page with usage disclosure
body = await getSearchPage(taskId, { limit: 50, includeUsage: true });
const { results, stats } = body.data;
console.log(`${stats.results_count} results across ${stats.pages_fetched} pages`);
results.slice(0, 5).forEach((item) =>
  console.log(item.published_at, item.stats.likes, item.url)
);
if (body.usage) console.log("Credits charged:", body.usage.total_credits);

Don’t pass include_usage on the submit (POST) call — it’s ignored because billing happens after the 202 response. Pass it on the polling GET, and only expect a usage block once task_status=completed (failed tasks have all charges refunded).

Choosing Between Profile and Keyword Search

Use case	Endpoint
Collect one creator’s catalog	Profile scrape
Track a hashtag, topic, or trend across creators	Keyword search
Filter by date range and likes	Both (add `after_datetime` / `before_datetime`, `min_likes` / `max_likes`)
Filter by views	Keyword search (`min_views` / `max_views`)
Maximize coverage of a keyword	Keyword search with `parallel_search_slices` up to `4` (no date window)
Most popular recent videos for a keyword	Keyword search with `sort_by: "most_liked"` and `published_within`

Get Started

User Guides

Overview

Profile Scrape

Keyword Search

Prerequisites

Billing

Searching a TikTok Profile

With the SDK

With raw HTTP

1. Submit the scrape

2. Poll until completed and page through results

Searching TikTok by Keyword

With the SDK

With raw HTTP

1. Submit the search

2. Poll, paginate, and read usage

Choosing Between Profile and Keyword Search

Next Steps

​Overview

Profile Scrape

Keyword Search

​Prerequisites

​Billing

​Searching a TikTok Profile

​With the SDK

​With raw HTTP

​1. Submit the scrape

​2. Poll until completed and page through results

​Searching TikTok by Keyword

​With the SDK

​With raw HTTP

​1. Submit the search

​2. Poll, paginate, and read usage

​Choosing Between Profile and Keyword Search

​Next Steps

Overview

Prerequisites

Billing

Searching a TikTok Profile

With the SDK

With raw HTTP

1. Submit the scrape

2. Poll until completed and page through results

Searching TikTok by Keyword

With the SDK

With raw HTTP

1. Submit the search

2. Poll, paginate, and read usage

Choosing Between Profile and Keyword Search

Next Steps