KOLens Watchlist API
The Watchlist API from KOLens — 3 operation(s) for watchlist.
The Watchlist API from KOLens — 3 operation(s) for watchlist.
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-watchlist-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 Watchlist API
description: KOLens — TikTok KOL Intelligence API. Search keywords, extract KOL profiles, collect contact info, export reports.
version: 1.0.0
tags:
- name: Watchlist
paths:
/api/watchlist:
get:
tags:
- Watchlist
summary: List Watchlist
description: 'Return the user''s watchlist as a single significance-ranked change
digest.
One call yields everything the watchlist UI needs: per-entry identity,
current stats, 7d/30d snapshot deltas, recent activity events, the
"what changed" signal badges, a cached LLM activity summary if present,
and a 0-100 significance score + tier. ``entries`` is sorted by
``significance.score`` descending — the most-changed creator first.
No ``?signals=`` flag any more: the digest IS the response. The
frontend must not fan out to ``GET /api/kols/{username}`` per row.'
operationId: list_watchlist_api_watchlist_get
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
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/WatchlistDigestResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
post:
tags:
- Watchlist
summary: Add Watchlist
description: 'Idempotent: re-adding an existing (user, username, platform) returns the existing row.
``platform`` defaults to ``"tiktok"`` so legacy callers (web Star
button, plugin) keep working unchanged. The same handle on a
different platform is a separate row — the unique index is
(user_id, username, platform).'
operationId: add_watchlist_api_watchlist_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/WatchlistAdd'
responses:
'201':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/WatchlistEntryOut'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/watchlist/{username}:
delete:
tags:
- Watchlist
summary: Remove Watchlist
description: 'Remove a (user, username, platform) row from the watchlist.
``?platform=`` is a query parameter; default is ``"tiktok"`` so
legacy clients that pass no platform keep deleting the TikTok row.
Idempotent — delete-of-nonexistent is a no-op (returns 204).'
operationId: remove_watchlist_api_watchlist__username__delete
security:
- HTTPBearer: []
parameters:
- name: username
in: path
required: true
schema:
type: string
title: Username
- name: platform
in: query
required: false
schema:
type: string
default: tiktok
title: Platform
- name: x-kolens-user-id
in: header
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: X-Kolens-User-Id
responses:
'204':
description: Successful Response
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/watchlist/{username}/audience:
put:
tags:
- Watchlist
summary: Update Watchlist Audience Prefs
description: 'AP-4: per-row audience auto-refresh prefs.
PATCH-style — only the fields present in the body are touched.
Sample size must be one of the priced tiers (200 / 500 / 2000) so
the scheduler always knows what to charge.'
operationId: update_watchlist_audience_prefs_api_watchlist__username__audience_put
security:
- HTTPBearer: []
parameters:
- name: username
in: path
required: true
schema:
type: string
title: Username
- 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/WatchlistAudiencePrefs'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/WatchlistEntryOut'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
components:
schemas:
ActivitySummaryOut:
properties:
period:
type: string
title: Period
summary:
anyOf:
- type: string
- type: 'null'
title: Summary
highlights:
items:
type: string
type: array
title: Highlights
default: []
generated_at:
anyOf:
- type: string
- type: 'null'
title: Generated At
type: object
required:
- period
title: ActivitySummaryOut
description: The cached LLM ``DBKolActivitySummary`` for this KOL, if one exists.
ChangeWindowOut:
properties:
window_days:
type: integer
title: Window Days
snapshots_count:
type: integer
title: Snapshots Count
follower_delta:
anyOf:
- type: integer
- type: 'null'
title: Follower Delta
follower_delta_pct:
anyOf:
- type: number
- type: 'null'
title: Follower Delta Pct
avg_views_delta:
anyOf:
- type: number
- type: 'null'
title: Avg Views Delta
avg_views_delta_pct:
anyOf:
- type: number
- type: 'null'
title: Avg Views Delta Pct
avg_views_unreliable:
type: boolean
title: Avg Views Unreliable
default: false
engagement_rate_delta:
anyOf:
- type: number
- type: 'null'
title: Engagement Rate Delta
type: object
required:
- window_days
- snapshots_count
title: ChangeWindowOut
description: Snapshot-derived deltas over one time window (7d or 30d).
WatchlistDigestSummary:
properties:
total:
type: integer
title: Total
n_act_now:
type: integer
title: N Act Now
n_notable:
type: integer
title: N Notable
n_quiet:
type: integer
title: N Quiet
n_new_viral_videos:
type: integer
title: N New Viral Videos
n_newly_dormant:
type: integer
title: N Newly Dormant
total_unseen:
type: integer
title: Total Unseen
type: object
required:
- total
- n_act_now
- n_notable
- n_quiet
- n_new_viral_videos
- n_newly_dormant
- total_unseen
title: WatchlistDigestSummary
description: 'Top-level roll-up — answers "what changed across my watchlist?"
in seven integers so the UI can render a header without scanning
every entry.'
IdentityOut:
properties:
username:
type: string
title: Username
display_name:
anyOf:
- type: string
- type: 'null'
title: Display Name
avatar_url:
anyOf:
- type: string
- type: 'null'
title: Avatar Url
verified:
type: boolean
title: Verified
default: false
type: object
required:
- username
title: IdentityOut
VideoBriefOut:
properties:
video_id:
type: string
title: Video Id
url:
anyOf:
- type: string
- type: 'null'
title: Url
thumbnail_url:
anyOf:
- type: string
- type: 'null'
title: Thumbnail Url
caption:
anyOf:
- type: string
- type: 'null'
title: Caption
views:
anyOf:
- type: integer
- type: 'null'
title: Views
likes:
anyOf:
- type: integer
- type: 'null'
title: Likes
created_at:
anyOf:
- type: string
- type: 'null'
title: Created At
is_sponsored:
type: boolean
title: Is Sponsored
default: false
is_ad:
type: boolean
title: Is Ad
default: false
type: object
required:
- video_id
title: VideoBriefOut
ChangesOut:
properties:
windows:
additionalProperties:
$ref: '#/components/schemas/ChangeWindowOut'
type: object
title: Windows
default: {}
recent_events:
items:
$ref: '#/components/schemas/ActivityEventOut'
type: array
title: Recent Events
default: []
activity_summary:
anyOf:
- $ref: '#/components/schemas/ActivitySummaryOut'
- type: 'null'
type: object
title: ChangesOut
WatchlistEntryOut:
properties:
id:
type: string
title: Id
user_id:
type: string
title: User Id
username:
type: string
title: Username
platform:
type: string
title: Platform
default: tiktok
added_at:
type: string
title: Added At
last_refreshed_at:
anyOf:
- type: string
- type: 'null'
title: Last Refreshed At
next_refresh_at:
anyOf:
- type: string
- type: 'null'
title: Next Refresh At
is_paused:
type: boolean
title: Is Paused
audience_auto_refresh:
type: boolean
title: Audience Auto Refresh
default: false
audience_refresh_interval_days:
type: integer
title: Audience Refresh Interval Days
default: 7
audience_sample_size:
type: integer
title: Audience Sample Size
default: 200
audience_last_refreshed_at:
anyOf:
- type: string
- type: 'null'
title: Audience Last Refreshed At
type: object
required:
- id
- user_id
- username
- added_at
- is_paused
title: WatchlistEntryOut
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
SignalOut:
properties:
kind:
type: string
title: Kind
severity:
type: string
title: Severity
label:
type: string
title: Label
detail:
anyOf:
- type: string
- type: 'null'
title: Detail
data:
anyOf:
- type: object
- type: 'null'
title: Data
type: object
required:
- kind
- severity
- label
title: SignalOut
description: One badge worth of "something changed since last check".
CurrentStatsOut:
properties:
follower_count:
anyOf:
- type: integer
- type: 'null'
title: Follower Count
avg_views:
anyOf:
- type: number
- type: 'null'
title: Avg Views
avg_engagement_rate:
anyOf:
- type: number
- type: 'null'
title: Avg Engagement Rate
type: object
title: CurrentStatsOut
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
WatchlistAudiencePrefs:
properties:
audience_auto_refresh:
anyOf:
- type: boolean
- type: 'null'
title: Audience Auto Refresh
audience_refresh_interval_days:
anyOf:
- type: integer
maximum: 90.0
minimum: 1.0
- type: 'null'
title: Audience Refresh Interval Days
audience_sample_size:
anyOf:
- type: integer
- type: 'null'
title: Audience Sample Size
type: object
title: WatchlistAudiencePrefs
description: 'PATCH-shape for ``PUT /api/watchlist/{username}/audience``.
All fields optional so the front-end toggle can flip just
``audience_auto_refresh`` without re-sending the others.'
WatchlistEntryDigest:
properties:
id:
type: string
title: Id
added_at:
type: string
title: Added At
is_paused:
type: boolean
title: Is Paused
platform:
type: string
title: Platform
default: tiktok
audience_auto_refresh:
type: boolean
title: Audience Auto Refresh
default: false
audience_refresh_interval_days:
type: integer
title: Audience Refresh Interval Days
default: 7
audience_sample_size:
type: integer
title: Audience Sample Size
default: 200
audience_last_refreshed_at:
anyOf:
- type: string
- type: 'null'
title: Audience Last Refreshed At
identity:
$ref: '#/components/schemas/IdentityOut'
current:
$ref: '#/components/schemas/CurrentStatsOut'
changes:
$ref: '#/components/schemas/ChangesOut'
signals:
items:
$ref: '#/components/schemas/SignalOut'
type: array
title: Signals
default: []
latest_video:
anyOf:
- $ref: '#/components/schemas/VideoBriefOut'
- type: 'null'
days_since_last_post:
anyOf:
- type: integer
- type: 'null'
title: Days Since Last Post
outreach:
anyOf:
- $ref: '#/components/schemas/OutreachBriefOut'
- type: 'null'
recommendation_score:
anyOf:
- type: integer
- type: 'null'
title: Recommendation Score
significance:
$ref: '#/components/schemas/SignificanceOut'
unseen:
type: boolean
title: Unseen
default: false
type: object
required:
- id
- added_at
- is_paused
- identity
- current
- changes
- significance
title: WatchlistEntryDigest
description: One watched KOL, fully change-oriented — no per-row follow-up call.
SignificanceOut:
properties:
score:
type: integer
title: Score
tier:
type: string
title: Tier
reasons:
items:
type: string
type: array
title: Reasons
default: []
type: object
required:
- score
- tier
title: SignificanceOut
WatchlistAdd:
properties:
username:
type: string
maxLength: 100
minLength: 1
title: Username
platform:
type: string
maxLength: 20
minLength: 1
title: Platform
default: tiktok
type: object
required:
- username
title: WatchlistAdd
OutreachBriefOut:
properties:
conversation_id:
type: string
title: Conversation Id
status:
type: string
title: Status
last_event_at:
anyOf:
- type: string
- type: 'null'
title: Last Event At
days_since_last_event:
anyOf:
- type: integer
- type: 'null'
title: Days Since Last Event
event_count:
type: integer
title: Event Count
default: 0
type: object
required:
- conversation_id
- status
title: OutreachBriefOut
ActivityEventOut:
properties:
id:
type: string
title: Id
kind:
type: string
title: Kind
summary:
anyOf:
- type: object
- type: 'null'
title: Summary
created_at:
anyOf:
- type: string
- type: 'null'
title: Created At
seen_at:
anyOf:
- type: string
- type: 'null'
title: Seen At
unseen:
type: boolean
title: Unseen
default: false
type: object
required:
- id
- kind
title: ActivityEventOut
WatchlistDigestResponse:
properties:
digest:
$ref: '#/components/schemas/WatchlistDigestSummary'
entries:
items:
$ref: '#/components/schemas/WatchlistEntryDigest'
type: array
title: Entries
type: object
required:
- digest
- entries
title: WatchlistDigestResponse
securitySchemes:
HTTPBearer:
type: http
scheme: bearer