KOLens Scraping API

The Scraping API from KOLens — 8 operation(s) for scraping.

GitHub OpenAPI

Operations 8

POST /api/scrape Submit Scrape Job #
GET /api/jobs List Jobs #
GET /api/jobs/{job_id} Get Job Status #
GET /api/jobs/{job_id}/stream Stream Job Status #
POST /api/jobs/{job_id}/cancel Cancel Job #
GET /api/jobs/{job_id}/events Get Job Events #
GET /api/jobs/{job_id}/videos Get Job Videos #
GET /api/jobs/{job_id}/export Export Job Results #

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • 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.
All 92 tools →

Call it yourself

curl for this page
This API
curl "https://apis.io/api/v1/apis/kolens-ai:kolens-ai-scraping-api"
All apis
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.

Get an API 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 Specification

kolens-ai-scraping-api-openapi.yml Raw ↑
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