---
title: "Submit Scrape Job"
method: POST
path: "/api/scrape"
tags: ["Scraping"]
---

# Submit Scrape Job

`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

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.

## Headers

- `x-kolens-user-id` string, nullable

## Request body

- ScrapeRequest
  - `keyword` string, required: TikTok search keyword
  - `max_videos` integer
  - `max_scrolls` integer: Max scroll iterations. 0 = auto (calculated from max_videos).
  - `fetch_contacts` boolean
  - `fetch_account_stats` boolean
  - `scraper_mode` string: Scraper browser backend: 'local' or 'cloud' (BrowserBase). Cloud falls back to local automatically if BB is not configured.
  - `data_source` string, 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 `202`

Successful Response

- ScrapeResponse
  - `job_id` string, required
  - `status` string, required
  - `keyword` string, required
  - `estimated_seconds` integer, required
  - `query_plan` QueryPlanEcho: Display-only echo of how the NL query planner interpreted a typed intent sentence (Phase 1). Returned on the create / search-submit response so the UI can show "Interpreted as: [terms] · filters". Only present when the planner flag is ON *and* the planner produced a real (non-passthrough) interpretation — null otherwise so existing clients ignore it. An editable confirm step is Phase 2.
    - `raw_query` string, required
    - `search_terms` string[]
    - `filters` object
    - `market` string, nullable
    - `language` string, nullable
    - `notes` string

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/kolens/apis/kolens-api.md) · [All operations](https://skmtc.dev/kolens/apis/kolens-api/llms.txt) · [OpenAPI document](https://skmtc.dev/kolens/apis/kolens-api/revisions/5d6865ab0a24?raw)