KOLens REST API — an influencer marketing API for developers

Authentication

Create a key in the web app under Account → API keys. Every /api/* request carries it as a Bearer token. Keys are tied to your user for billing — keep them server-side, never in client code.

export KOLENS_API_KEY="kol_xxxxxxxxxxxx"
curl https://kolens.ai/api/kols \
  -H "Authorization: Bearer $KOLENS_API_KEY"

Core flow: search → poll → query

1. Submit a keyword scrape

curl -X POST https://kolens.ai/api/scrape \
  -H "Authorization: Bearer $KOLENS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"keyword": "skincare routine", "max_videos": 50, "region": "US"}'
# → 202 {"job_id": "…", "status": "queued", …}

The other platforms mirror the shape: POST /api/instagram/scrape {"hashtag": "kbeauty", "max_videos": 50} · POST /api/x/scrape {"keyword": "ai tools", "max_tweets": 50} · POST /api/douyin/scrape {"keyword": "美妆", "max_videos": 50}. All return 202 with a job id; all bill max(1, ceil(results ÷ 10)) credits, refunded on failure.

2. Poll the job

curl https://kolens.ai/api/jobs/$JOB_ID \
  -H "Authorization: Bearer $KOLENS_API_KEY"
# → {"status": "completed", "kol_count": 12, "total_videos": 50, …}
# Excel download:
#   GET /api/jobs/$JOB_ID/export

Statuses move queued → running → completed (or failed). Poll with backoff (a few seconds is plenty); GET /api/jobs lists recent jobs.

3. Query the creator database

curl "https://kolens.ai/api/kols?keyword=skincare%20routine\
&require_email=true&min_engagement_rate=0.04\
&min_followers=10000&sort_by=avg_views" \
  -H "Authorization: Bearer $KOLENS_API_KEY"

Key filters: platform, min/max_followers, min_engagement_rate (decimal — 0.04 = 4%), min_avg_views, country (ISO-2), category, require_email, require_website, hide_sellers, verified_only, scope=personal|team|both, sort_by. Add llm_friendly=true to receive a pre-digested summary, risk_flags and next_actions per row — designed for feeding LLMs. Single creator: GET /api/kols/{username}; audience: GET /api/kols/{username}/audience.

Endpoint families

Limits & errors

• Rate limit: 5 scrape submissions per minute per key; reads are not separately limited (poll politely).
• 401 — missing/invalid key · 402 — insufficient credits (job not started) · 404 — unknown resource · 422 — validation error with field details.
• Interactive OpenAPI (Swagger) docs with every schema live on the API service itself — this page covers the stable core.