KOLens Video Tracking API

The Video Tracking API from KOLens — 11 operation(s) for video tracking.

GitHub OpenAPI

Operations 11

POST /api/videos/track Track Video #
GET /api/videos/tracked List Tracked #
GET /api/videos/{video_id}/tracking Get Video Tracking #
POST /api/videos/{video_id}/refresh Refresh Video Metrics #
GET /api/videos/{video_id}/comments Get Video Comments #
POST /api/videos/{video_id}/comments/refresh Refresh Video Comments #
POST /api/videos/{video_id}/summary Generate Video Summary #
PUT /api/videos/{video_id}/campaign-tag Set Video Campaign Tag #
PUT /api/videos/{video_id}/keywords Set Video Keywords #
DELETE /api/videos/{video_id}/track Untrack Video #
GET /api/videos/compare Compare Videos #

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-video-tracking-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-video-tracking-api-openapi.yml Raw ↑
openapi: 3.2.0
info:
  title: KOLens Video Tracking API
  description: KOLens — TikTok KOL Intelligence API. Search keywords, extract KOL profiles, collect contact info, export reports.
  version: 1.0.0
tags:
- name: Video Tracking
paths:
  /api/videos/track:
    post:
      tags:
      - Video Tracking
      summary: Track Video
      description: 'Start tracking a published TikTok video.


        Idempotent on ``(user, platform, video_id)``: re-tracking the same video

        returns (and re-activates) the existing row. A best-effort first capture

        runs inline so the growth curve has a t0 point when Apify is configured;

        on failure (or when ``APIFY_API_TOKEN`` is unset) the row is left

        immediately due so the scheduler captures on its next tick.'
      operationId: track_video_api_videos_track_post
      security:
      - HTTPBearer: []
      parameters:
      - 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
      - name: x-kolens-locale
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Kolens-Locale
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TrackVideoRequest'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrackedVideoOut'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/videos/tracked:
    get:
      tags:
      - Video Tracking
      summary: List Tracked
      description: 'List tracked videos visible to the caller, partitioned own vs

        competitor, each with its latest snapshot. Frontends render two

        columns from this.


        ``scope`` is what the Personal/Team switcher sends. It used to be

        accepted by the proxy and dropped here (FastAPI ignores unknown

        query params), which is why the toggle appeared to do nothing on

        this page.'
      operationId: list_tracked_api_videos_tracked_get
      security:
      - HTTPBearer: []
      parameters:
      - name: label
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: 'Filter: own | competitor'
          title: Label
        description: 'Filter: own | competitor'
      - name: scope
        in: query
        required: false
        schema:
          type: string
          description: personal | team | both — which rows count as visible
          default: both
          title: Scope
        description: personal | team | both — which rows count as visible
      - 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: object
                title: Response List Tracked Api Videos Tracked Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/videos/{video_id}/tracking:
    get:
      tags:
      - Video Tracking
      summary: Get Video Tracking
      description: 'Single-video detail: metric time-series + 7d/30d deltas + content.

        Comments + audience arrive in P2/P3.'
      operationId: get_video_tracking_api_videos__video_id__tracking_get
      security:
      - HTTPBearer: []
      parameters:
      - name: video_id
        in: path
        required: true
        schema:
          type: string
          title: Video 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:
                type: object
                title: Response Get Video Tracking Api Videos  Video Id  Tracking Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/videos/{video_id}/refresh:
    post:
      tags:
      - Video Tracking
      summary: Refresh Video Metrics
      description: 'Re-capture a tracked video''s metrics via Apify right now.


        The on-demand counterpart to the scheduler tick — used by the "retry"

        button when a capture failed (e.g. a transient Apify error or a quota

        limit that has since been raised). Best-effort: an Apify failure or unset

        token returns ``{"ok": False, "error": ...}`` instead of a 5xx, and the

        error is stamped on the row so the UI can keep showing it. On success the

        cadence anchors advance and ``last_error`` is cleared.'
      operationId: refresh_video_metrics_api_videos__video_id__refresh_post
      security:
      - HTTPBearer: []
      parameters:
      - name: video_id
        in: path
        required: true
        schema:
          type: string
          title: Video 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:
                type: object
                title: Response Refresh Video Metrics Api Videos  Video Id  Refresh Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/videos/{video_id}/comments:
    get:
      tags:
      - Video Tracking
      summary: Get Video Comments
      description: 'Paginated comment stream (most-liked first) + sentiment summary for a

        tracked video. EPIC #514 Phase 2.'
      operationId: get_video_comments_api_videos__video_id__comments_get
      security:
      - HTTPBearer: []
      parameters:
      - name: video_id
        in: path
        required: true
        schema:
          type: string
          title: Video Id
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 200
          minimum: 1
          default: 50
          title: Limit
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          default: 0
          title: Offset
      - 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: object
                title: Response Get Video Comments Api Videos  Video Id  Comments Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/videos/{video_id}/comments/refresh:
    post:
      tags:
      - Video Tracking
      summary: Refresh Video Comments
      description: 'Fetch the latest comments via Apify now and (re)classify sentiment.


        Returns the capture counts + the refreshed summary. Best-effort: an Apify

        failure or unset token returns ``{"ok": False, "error": ...}`` rather than

        a 5xx so the UI can show a soft "couldn''t refresh" state.'
      operationId: refresh_video_comments_api_videos__video_id__comments_refresh_post
      security:
      - HTTPBearer: []
      parameters:
      - name: video_id
        in: path
        required: true
        schema:
          type: string
          title: Video Id
      - name: max_comments
        in: query
        required: false
        schema:
          type: integer
          maximum: 500
          minimum: 1
          default: 100
          title: Max Comments
      - 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: object
                title: Response Refresh Video Comments Api Videos  Video Id  Comments Refresh Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/videos/{video_id}/summary:
    post:
      tags:
      - Video Tracking
      summary: Generate Video Summary
      description: 'On-demand AI summary of the tracked video (content meaning, quality

        verdict, buyer-intent read). Cached on the row — repeat calls return the

        cached result unless ``refresh=true`` OR the cached summary was written

        in a different language than ``lang`` (so the summary matches the page

        language).'
      operationId: generate_video_summary_api_videos__video_id__summary_post
      security:
      - HTTPBearer: []
      parameters:
      - name: video_id
        in: path
        required: true
        schema:
          type: string
          title: Video Id
      - name: refresh
        in: query
        required: false
        schema:
          type: boolean
          description: Force re-analysis even if cached
          default: false
          title: Refresh
        description: Force re-analysis even if cached
      - name: lang
        in: query
        required: false
        schema:
          type: string
          description: UI locale — the summary prose is written in this language
          default: en
          title: Lang
        description: UI locale — the summary prose is written in this language
      - 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: object
                title: Response Generate Video Summary Api Videos  Video Id  Summary Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/videos/{video_id}/campaign-tag:
    put:
      tags:
      - Video Tracking
      summary: Set Video Campaign Tag
      description: 'Correct the campaign this video is grouped under.


        The label is otherwise guessed from the post''s caption + hashtags,

        which works until a video carries several. "#fyp #goglowai #skincare"

        has no way of announcing which one is the campaign, and a wrong guess

        does not just mislabel one card — it moves that video''s views into

        another campaign''s totals, so the number an operator reports to a

        client is wrong. Hence a correction, and hence the correction wins

        over detection rather than merely competing with it.


        Sending null or an empty string clears the override and restores

        detection — that is how a bad correction gets undone.


        Editable by any workspace member who can see the video, unlike alert

        keywords next door. The distinction is what the field does: keywords

        configure the OWNER''S notifications, while this is a shared

        bookkeeping fact feeding totals the whole team reads. A teammate who

        can see a mislabelled video and cannot fix it just files a complaint

        instead.'
      operationId: set_video_campaign_tag_api_videos__video_id__campaign_tag_put
      security:
      - HTTPBearer: []
      parameters:
      - name: video_id
        in: path
        required: true
        schema:
          type: string
          title: Video 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
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CampaignTagRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                title: Response Set Video Campaign Tag Api Videos  Video Id  Campaign Tag Put
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/videos/{video_id}/keywords:
    put:
      tags:
      - Video Tracking
      summary: Set Video Keywords
      description: 'Set the tracked video''s custom comment-alert keywords. A new comment

        matching any of these (or the built-in purchase-intent set) fires an

        alert through the user''s alert channel. Normalised: lowercase, trimmed,

        deduped, capped (50 keywords × 60 chars).


        Owner-only even when the row is shared with the team: these keywords

        decide what the OWNER gets pinged about, and a teammate rewriting

        them changes someone else''s notifications without telling them.'
      operationId: set_video_keywords_api_videos__video_id__keywords_put
      security:
      - HTTPBearer: []
      parameters:
      - name: video_id
        in: path
        required: true
        schema:
          type: string
          title: Video 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
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/KeywordsRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                title: Response Set Video Keywords Api Videos  Video Id  Keywords Put
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/videos/{video_id}/track:
    delete:
      tags:
      - Video Tracking
      summary: Untrack Video
      description: 'Stop tracking a video (hard delete of the subscription row). The

        captured snapshots stay — they remain useful history and feed trending

        detection.


        Owner-only: a shared row is still somebody''s tracking, and deleting

        it would end their refreshes and their alerts. Removing a teammate''s

        video from your own view is a different feature (un-sharing), not

        this one.'
      operationId: untrack_video_api_videos__video_id__track_delete
      security:
      - HTTPBearer: []
      parameters:
      - name: video_id
        in: path
        required: true
        schema:
          type: string
          title: Video 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:
                type: object
                title: Response Untrack Video Api Videos  Video Id  Track Delete
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/videos/compare:
    get:
      tags:
      - Video Tracking
      summary: Compare Videos
      description: 'Own-vs-competitor comparison: returns each requested video''s detail

        payload (curve + latest + deltas) side by side.'
      operationId: compare_videos_api_videos_compare_get
      security:
      - HTTPBearer: []
      parameters:
      - name: ids
        in: query
        required: true
        schema:
          type: string
          description: Comma-separated tracked video_ids
          title: Ids
        description: Comma-separated tracked video_ids
      - 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: object
                title: Response Compare Videos Api Videos Compare Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    TrackedVideoOut:
      properties:
        id:
          type: string
          title: Id
        video_id:
          type: string
          title: Video Id
        video_url:
          type: string
          title: Video Url
        platform:
          type: string
          title: Platform
        label:
          type: string
          title: Label
        note:
          anyOf:
          - type: string
          - type: 'null'
          title: Note
        author_username:
          anyOf:
          - type: string
          - type: 'null'
          title: Author Username
        cadence_hours:
          type: integer
          title: Cadence Hours
        is_active:
          type: boolean
          title: Is Active
        last_refreshed_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Last Refreshed At
        next_refresh_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Next Refresh At
        last_error:
          anyOf:
          - type: string
          - type: 'null'
          title: Last Error
        created_at:
          type: string
          format: date-time
          title: Created At
      type: object
      required:
      - id
      - video_id
      - video_url
      - platform
      - label
      - note
      - author_username
      - cadence_hours
      - is_active
      - last_refreshed_at
      - next_refresh_at
      - last_error
      - created_at
      title: TrackedVideoOut
    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
    KeywordsRequest:
      properties:
        keywords:
          items:
            type: string
          type: array
          title: Keywords
      type: object
      title: KeywordsRequest
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    TrackVideoRequest:
      properties:
        url:
          type: string
          maxLength: 1000
          minLength: 5
          title: Url
          description: TikTok video URL, Instagram reel/post URL, a vt.tiktok.com short link, or the whole share message — we extract the link.
        label:
          type: string
          title: Label
          description: '''own'' (your collab) | ''competitor'''
          default: own
        note:
          anyOf:
          - type: string
            maxLength: 2000
          - type: 'null'
          title: Note
        cadence_hours:
          anyOf:
          - type: integer
            maximum: 168.0
            minimum: 1.0
          - type: 'null'
          title: Cadence Hours
          description: Refresh cadence; defaults to 24h
      type: object
      required:
      - url
      title: TrackVideoRequest
    CampaignTagRequest:
      properties:
        campaign_tag:
          anyOf:
          - type: string
            maxLength: 120
          - type: 'null'
          title: Campaign Tag
          description: Override the detected campaign label. Null/empty restores detection.
      type: object
      title: CampaignTagRequest
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer