---
title: "Get Kol Profile"
method: GET
path: "/api/kols/{username}"
tags: ["KOL Database"]
---

# Get Kol Profile

`GET /api/kols/{username}`

## 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/{username}`
- Auth: HTTP bearer

Full KOL profile including contact info and all keywords they appeared under.

Scoped: returns 404 if the caller has not discovered this author and
their active workspace hasn't either — same response as if the
author didn't exist at all, so we don't leak "this row exists but
isn't yours" via a 403.

With ``lookup_if_missing=true`` (EPIC #275), a 404 path triggers a
single-handle on-demand lookup on the chosen ``platform`` and then
re-queries. Cheap when the row already exists; pricier when it
doesn't (one credit per 50 videos at minimum, refunded on failure).

## Path parameters

- `username` string, required

## Query parameters

- `lookup_if_missing` boolean: If the row isn't in the DB yet, run a single-handle lookup via Apify before responding (EPIC #275). Charges credits + respects the chosen ``platform``. Default false keeps the endpoint cheap for the read-only common case.
- `platform` string: Platform for the on-demand lookup when lookup_if_missing=true

## Headers

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

## Response `200`

Successful Response

- KOLProfile
  - `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[], required
  - `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
  - `bio` string, nullable, required
  - `bio_zh` string, nullable
  - `median_views` number, nullable, required
  - `max_views` integer, nullable, required
  - `avg_likes` number, nullable, required
  - `total_videos_in_db` integer, required
  - `tiktok_id` string, nullable
  - `profile_url` string, nullable
  - `is_private` boolean
  - `total_videos` integer, nullable
  - `total_hearts` integer, nullable
  - `instagram_id` string, nullable
  - `youtube_channel_id` string, nullable
  - `x_handle` string, nullable
  - `x_user_id` string, nullable
  - `xhs_user_id` string, nullable
  - `douyin_id` string, nullable
  - `douyin_sec_uid` string, nullable
  - `account_created_at` string, nullable
  - `first_video_at` string, nullable
  - `last_video_at` string, nullable
  - `posting_cadence_days` number, nullable
  - `videos_per_week` number, 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)