---
title: "List Kols"
method: GET
path: "/api/kols"
tags: ["KOL Database"]
---

# List Kols

`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 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.

## Query parameters

- `keyword` string, nullable: Filter by keyword found in their videos
- `job_id` string, nullable: Filter to authors discovered by a specific scrape job
- `role` string, nullable: KOL | Seller
- `platform` string, nullable: tiktok | instagram | x | douyin
- `min_followers` integer
- `max_followers` integer, nullable
- `require_email` boolean
- `require_website` boolean
- `min_avg_views` number, nullable
- `engagement_rate_min` number, nullable: Minimum engagement rate %
- `engagement_rate_max` number, nullable: Maximum engagement rate %
- `avg_views_min` number, nullable: Minimum average views
- `avg_views_max` number, nullable: Maximum average views
- `min_posts_per_month` number, nullable: Minimum posts per month (from videos_per_week)
- `active_within_days` integer, nullable: Posted at least once in the last N days
- `country` string, nullable: Filter by country
- `category` string, nullable: Filter by category
- `gender` string, nullable: Filter by gender
- `verified_only` boolean: Only verified accounts
- `has_instagram` boolean: Has Instagram link
- `has_youtube` boolean: Has YouTube link
- `hide_sellers` boolean: Hide brand / store accounts (is_seller_like=True)
- `looked_up_only` boolean: Only authors that came in via handle-lookup
- `max_reach_ratio` number, nullable: Hide accounts whose avg views exceed N× their followers (reposter / aggregator signal). Try 20.
- `sort_by` string: effective_reach | avg_views | followers | engagement_rate | last_updated
- `scope` string: Workspace-scope toggle (EPIC #114 Phase 3): personal = only your own discoveries, team = only discoveries from your active workspace, both = the union (default).
- `page` integer
- `per_page` integer
- `llm_friendly` boolean: Add LLM-friendly pre-digested facets

## Headers

- `x-kolens-user-id` string, nullable
- `x-kolens-workspace-id` string, nullable

## Response `200`

Successful Response

- KOLListResponse
  - `total` integer, required
  - `page` integer, required
  - `per_page` integer, required
  - `kols` KOLSummary[], required
    - `username` string, required
    - `platform` string, nullable
    - `display_name` string, nullable, required
    - `follower_count` integer, nullable, required
    - `is_verified` boolean, required
    - `avg_views` number, nullable, required
    - `avg_engagement_rate` number, nullable, required
    - `view_to_follower_ratio` number, nullable, required
    - `has_email` boolean, required
    - `has_website` boolean, required
    - `email` string, nullable
    - `phone` string, nullable
    - `contact` ContactSchema
      - `email` string, nullable
      - `phone` string, nullable
      - `website` string, nullable
      - `instagram` string, nullable
      - `youtube` string, nullable
      - `linktree_url` string, nullable
    - `first_seen_at` string, required
    - `last_updated_at` string, required
    - `avatar_url` string, nullable
    - `avatar_url_cached` string, nullable
    - `keywords_found_in` string[]
    - `audience_data` AudienceData: Normalized audience demographics — present only when enrichment has been run.
      - `gender` object, nullable
      - `age` object, nullable
      - `top_countries` object[], nullable
      - `top_interests` string[], nullable
    - `country` string, nullable
    - `city` string, nullable
    - `language` string, nullable
    - `category` string, nullable
    - `category_inferred` string, nullable
    - `category_source` string, nullable
    - `gender` string, nullable
    - `llm` object, nullable
    - `display_name_zh` string, nullable
    - `category_zh` string, nullable
  - `llm_meta` object, nullable

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/kolens/apis/kolens-api.md) · [All operations](https://skmtc.dev/kolens/apis/kolens-api/llms.txt) · [OpenAPI document](https://skmtc.dev/kolens/apis/kolens-api/revisions/5d6865ab0a24?raw)