KOLens Video Tracking API
The Video Tracking API from KOLens — 11 operation(s) for video tracking.
The Video Tracking API from KOLens — 11 operation(s) for video tracking.
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-video-tracking-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 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