Scraping

Submit Scrape Job

Submit a TikTok scrape job. Returns immediately with a job_id. Poll GET /api/jobs/{job_id} to track progress.

Credits: pre-charged at submit time based on max_videos (the cost driver — Apify pages fetched). Default formula is ceil(max_videos / 10) credits. Insufficient balance returns 402; no work is done. If the worker subsequently fails before persisting any videos, scrape_runner refunds the pre-charge.

post/api/scrape

Request

  • Base URL: https://api.kolens.ai (the document declares no server; this is the origin it was published from)
  • URL: https://api.kolens.ai/api/scrape
  • Auth: HTTP bearer

Headers

x-kolens-user-idstring nullable

Request body

keywordstring required

TikTok search keyword

max_videosinteger
max_scrollsinteger

Max scroll iterations. 0 = auto (calculated from max_videos).

fetch_contactsboolean
fetch_account_statsboolean
scraper_modestring

Scraper browser backend: 'local' or 'cloud' (BrowserBase). Cloud falls back to local automatically if BB is not configured.

data_sourcestring nullable

Where to source data from: 'scraper' (default, Playwright-based) or 'apify' (Apify TikTok actor, webhook-driven). When unset the server picks the default for the deployment.

Response

Successful Response

job_idstring required
statusstring required
keywordstring required
estimated_secondsinteger required

Changes

No recorded changes to this operation across all 1 revision of this API.