KOLens Scraping API
The Scraping API from KOLens — 8 operation(s) for scraping.
The Scraping API from KOLens — 8 operation(s) for scraping.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/kolens-ai:kolens-ai-scraping-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. By signing up you are subscribing to the APIs.io and API Evangelist newsletters — you can unsubscribe from any issue. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: KOLens Scraping API
description: KOLens — TikTok KOL Intelligence API. Search keywords, extract KOL profiles, collect contact info, export reports.
version: 1.0.0
tags:
- name: Scraping
paths:
/api/scrape:
post:
tags:
- Scraping
summary: Submit Scrape Job
description: '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.'
operationId: submit_scrape_job_api_scrape_post
security:
- HTTPBearer: []
parameters:
- name: x-kolens-user-id
in: header
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: X-Kolens-User-Id
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ScrapeRequest'
responses:
'202':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/ScrapeResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/jobs:
get:
tags:
- Scraping
summary: List Jobs
description: 'List recent scrape jobs.
When the Vercel proxy forwards ``X-Kolens-User-Id`` (the normal case
for the web app), restrict to jobs owned by that user — via either
direct job.user_id (set since the credits-attribution wiring landed)
or APIKey.user_id (covers legacy rows). Without the header (CLI /
cowork plugin) we keep the old per-api-key behavior.
EPIC #114 Phase 3: when ``X-Kolens-Workspace-Id`` is set and the
caller is a member, jobs are scoped to that workspace''s pool
(every member''s job is visible). Forging the header → 403.'
operationId: list_jobs_api_jobs_get
security:
- HTTPBearer: []
parameters:
- name: limit
in: query
required: false
schema:
type: integer
default: 20
title: Limit
- name: x-kolens-user-id
in: header
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: X-Kolens-User-Id
- name: x-kolens-workspace-id
in: header
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: X-Kolens-Workspace-Id
responses:
'200':
description: Successful Response
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/JobListItem'
title: Response List Jobs Api Jobs Get
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/jobs/{job_id}:
get:
tags:
- Scraping
summary: Get Job Status
description: 'Poll job progress. Check `status` field: queued → running → completed | failed.'
operationId: get_job_status_api_jobs__job_id__get
security:
- HTTPBearer: []
parameters:
- name: job_id
in: path
required: true
schema:
type: string
title: Job Id
- name: x-kolens-user-id
in: header
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: X-Kolens-User-Id
- name: x-kolens-workspace-id
in: header
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: X-Kolens-Workspace-Id
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/JobStatusResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/jobs/{job_id}/stream:
get:
tags:
- Scraping
summary: Stream Job Status
description: 'Stream job progress via Server-Sent Events. Sends a JSON event every 2s
until the job reaches a terminal state (completed/failed/cancelled).'
operationId: stream_job_status_api_jobs__job_id__stream_get
security:
- HTTPBearer: []
parameters:
- name: job_id
in: path
required: true
schema:
type: string
title: Job Id
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/jobs/{job_id}/cancel:
post:
tags:
- Scraping
summary: Cancel Job
description: Cancel a queued job or request cancellation for a running job.
operationId: cancel_job_api_jobs__job_id__cancel_post
security:
- HTTPBearer: []
parameters:
- name: job_id
in: path
required: true
schema:
type: string
title: Job Id
- name: x-kolens-user-id
in: header
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: X-Kolens-User-Id
- name: x-kolens-workspace-id
in: header
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: X-Kolens-Workspace-Id
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/CancelJobResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/jobs/{job_id}/events:
get:
tags:
- Scraping
summary: Get Job Events
description: Read the persisted execution timeline of a job.
operationId: get_job_events_api_jobs__job_id__events_get
security:
- HTTPBearer: []
parameters:
- name: job_id
in: path
required: true
schema:
type: string
title: Job Id
- name: limit
in: query
required: false
schema:
type: integer
default: 100
title: Limit
- name: x-kolens-user-id
in: header
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: X-Kolens-User-Id
- name: x-kolens-workspace-id
in: header
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: X-Kolens-Workspace-Id
responses:
'200':
description: Successful Response
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/JobEventResponse'
title: Response Get Job Events Api Jobs Job Id Events Get
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/jobs/{job_id}/videos:
get:
tags:
- Scraping
summary: Get Job Videos
description: 'List videos discovered by a single job.
``sort``: ``views`` (default) | ``likes`` | ``recent``.
``role``: optional filter on analyzer''s user_role tag
(``kol`` | ``seller`` | ``other``).
Output is intentionally a slim dict per video — the grid view only
needs thumbnail/url/caption/views/author, so we don''t pay for full
VideoOut serialization on 200-row payloads.'
operationId: get_job_videos_api_jobs__job_id__videos_get
security:
- HTTPBearer: []
parameters:
- name: job_id
in: path
required: true
schema:
type: string
title: Job Id
- name: sort
in: query
required: false
schema:
type: string
default: views
title: Sort
- name: role
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: Role
- name: limit
in: query
required: false
schema:
type: integer
default: 200
title: Limit
- name: offset
in: query
required: false
schema:
type: integer
default: 0
title: Offset
- name: x-kolens-user-id
in: header
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: X-Kolens-User-Id
responses:
'200':
description: Successful Response
content:
application/json:
schema:
type: array
items:
type: object
title: Response Get Job Videos Api Jobs Job Id Videos Get
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/jobs/{job_id}/export:
get:
tags:
- Scraping
summary: Export Job Results
description: 'Download the job results as an Excel file.
Only available when job status is ''completed''.'
operationId: export_job_results_api_jobs__job_id__export_get
security:
- HTTPBearer: []
parameters:
- name: job_id
in: path
required: true
schema:
type: string
title: Job Id
- name: format
in: query
required: false
schema:
type: string
default: xlsx
title: Format
- name: x-kolens-user-id
in: header
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: X-Kolens-User-Id
- name: x-kolens-workspace-id
in: header
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: X-Kolens-Workspace-Id
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
components:
schemas:
CancelJobResponse:
properties:
job_id:
type: string
title: Job Id
status:
type: string
title: Status
stage:
anyOf:
- type: string
- type: 'null'
title: Stage
cancel_requested:
type: boolean
title: Cancel Requested
type: object
required:
- job_id
- status
- stage
- cancel_requested
title: CancelJobResponse
JobEventResponse:
properties:
event_type:
type: string
title: Event Type
message:
type: string
title: Message
progress:
anyOf:
- type: integer
- type: 'null'
title: Progress
payload:
anyOf:
- type: object
- type: 'null'
title: Payload
created_at:
type: string
title: Created At
type: object
required:
- event_type
- message
- progress
- payload
- created_at
title: JobEventResponse
QueryPlanEcho:
properties:
raw_query:
type: string
title: Raw Query
search_terms:
items:
type: string
type: array
title: Search Terms
default: []
filters:
type: object
title: Filters
default: {}
market:
anyOf:
- type: string
- type: 'null'
title: Market
language:
anyOf:
- type: string
- type: 'null'
title: Language
notes:
type: string
title: Notes
default: ''
type: object
required:
- raw_query
title: QueryPlanEcho
description: '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.'
JobListItem:
properties:
job_id:
type: string
title: Job Id
keyword:
type: string
title: Keyword
status:
type: string
title: Status
kol_count:
type: integer
title: Kol Count
total_videos:
type: integer
title: Total Videos
progress:
type: integer
title: Progress
created_at:
type: string
title: Created At
completed_at:
anyOf:
- type: string
- type: 'null'
title: Completed At
credits_charged:
anyOf:
- type: number
- type: 'null'
title: Credits Charged
type: object
required:
- job_id
- keyword
- status
- kol_count
- total_videos
- progress
- created_at
- completed_at
title: JobListItem
ScrapeRequest:
properties:
keyword:
type: string
maxLength: 200
minLength: 1
title: Keyword
description: TikTok search keyword
max_videos:
type: integer
maximum: 500.0
minimum: 1.0
title: Max Videos
default: 100
max_scrolls:
type: integer
maximum: 50.0
minimum: 0.0
title: Max Scrolls
description: Max scroll iterations. 0 = auto (calculated from max_videos).
default: 0
fetch_contacts:
type: boolean
title: Fetch Contacts
default: true
fetch_account_stats:
type: boolean
title: Fetch Account Stats
default: true
scraper_mode:
type: string
title: Scraper Mode
description: 'Scraper browser backend: ''local'' or ''cloud'' (BrowserBase). Cloud falls back to local automatically if BB is not configured.'
default: cloud
data_source:
anyOf:
- type: string
- type: 'null'
title: Data Source
description: '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.'
type: object
required:
- keyword
title: ScrapeRequest
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
type: object
required:
- loc
- msg
- type
title: ValidationError
ScrapeResponse:
properties:
job_id:
type: string
title: Job Id
status:
type: string
title: Status
keyword:
type: string
title: Keyword
estimated_seconds:
type: integer
title: Estimated Seconds
query_plan:
anyOf:
- $ref: '#/components/schemas/QueryPlanEcho'
- type: 'null'
type: object
required:
- job_id
- status
- keyword
- estimated_seconds
title: ScrapeResponse
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
JobStatusResponse:
properties:
job_id:
type: string
title: Job Id
status:
type: string
title: Status
stage:
anyOf:
- type: string
- type: 'null'
title: Stage
progress:
type: integer
title: Progress
keyword:
type: string
title: Keyword
total_videos:
type: integer
title: Total Videos
kol_count:
type: integer
title: Kol Count
seller_count:
type: integer
title: Seller Count
created_at:
type: string
title: Created At
started_at:
anyOf:
- type: string
- type: 'null'
title: Started At
completed_at:
anyOf:
- type: string
- type: 'null'
title: Completed At
error_message:
anyOf:
- type: string
- type: 'null'
title: Error Message
export_ready:
type: boolean
title: Export Ready
attempt_count:
type: integer
title: Attempt Count
max_attempts:
type: integer
title: Max Attempts
cancel_requested:
type: boolean
title: Cancel Requested
queue_position:
anyOf:
- type: integer
- type: 'null'
title: Queue Position
credits_charged:
anyOf:
- type: number
- type: 'null'
title: Credits Charged
unique_kol_count:
anyOf:
- type: integer
- type: 'null'
title: Unique Kol Count
new_kol_count:
anyOf:
- type: integer
- type: 'null'
title: New Kol Count
owned_kol_count:
anyOf:
- type: integer
- type: 'null'
title: Owned Kol Count
track:
type: object
title: Track
type: object
required:
- job_id
- status
- stage
- progress
- keyword
- total_videos
- kol_count
- seller_count
- created_at
- started_at
- completed_at
- error_message
- export_ready
- attempt_count
- max_attempts
- cancel_requested
- queue_position
- track
title: JobStatusResponse
securitySchemes:
HTTPBearer:
type: http
scheme: bearer