KOL Database

List Kols

Query the accumulated KOL database with filters. Results are scoped to authors THIS caller's user OR active workspace has discovered — never returns rows surfaced by an unrelated user. The scope is enforced via an EXISTS subquery on user_discoveries regardless of the filter combination below.

get/api/kols

Request

  • Base URL: https://api.kolens.ai (the document declares no server; this is the origin it was published from)
  • URL: https://api.kolens.ai/api/kols
  • Auth: HTTP bearer

Query parameters

keywordstring nullable

Filter by keyword found in their videos

job_idstring nullable

Filter to authors discovered by a specific scrape job

rolestring nullable

KOL | Seller

platformstring nullable

tiktok | instagram | x | douyin

min_followersinteger
max_followersinteger nullable
require_emailboolean
require_websiteboolean
min_avg_viewsnumber nullable
engagement_rate_minnumber nullable

Minimum engagement rate %

engagement_rate_maxnumber nullable

Maximum engagement rate %

avg_views_minnumber nullable

Minimum average views

avg_views_maxnumber nullable

Maximum average views

min_posts_per_monthnumber nullable

Minimum posts per month (from videos_per_week)

active_within_daysinteger nullable

Posted at least once in the last N days

countrystring nullable

Filter by country

categorystring nullable

Filter by category

genderstring nullable

Filter by gender

verified_onlyboolean

Only verified accounts

has_instagramboolean

Has Instagram link

has_youtubeboolean

Has YouTube link

hide_sellersboolean

Hide brand / store accounts (is_seller_like=True)

looked_up_onlyboolean

Only authors that came in via handle-lookup

max_reach_rationumber nullable

Hide accounts whose avg views exceed N× their followers (reposter / aggregator signal). Try 20.

sort_bystring

effective_reach | avg_views | followers | engagement_rate | last_updated

scopestring

Workspace-scope toggle (EPIC #114 Phase 3): personal = only your own discoveries, team = only discoveries from your active workspace, both = the union (default).

pageinteger
per_pageinteger
llm_friendlyboolean

Add LLM-friendly pre-digested facets

Headers

x-kolens-user-idstring nullable
x-kolens-workspace-idstring nullable

Response

Successful Response

totalinteger required
pageinteger required
per_pageinteger required
llm_metaobject nullable

Changes

No recorded changes to this operation across all 1 revision of this API.