KOLens - TikTok KOL Intelligence API#

Overview#

KOLens is a TikTok KOL data scraping API that provides:

• Search TikTok KOLs by keyword
• Get KOL metrics (followers, avg views, engagement rate)
• Get contact information (email, website, Instagram, YouTube)

Setup#

1. Get API Credentials#

Contact the KOLens service administrator to obtain:

• KOLENS_API_KEY — Your personal API key
• KOLENS_API_URL — The KOLens API base URL

2. Set Environment Variables#

bash

export KOLENS_API_KEY="kol_your_key_here"
export KOLENS_API_URL="https://your-kolens-api-url.com"

Usage#

Step 1: Submit a Scraping Job#

bash

curl -X POST "${KOLENS_API_URL}/api/scrape" \
  -H "Authorization: Bearer ${KOLENS_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"keyword":"[KEYWORD]","max_videos":30,"fetch_contacts":true}'

Parameters:

• keyword (required): TikTok search keyword
• max_videos (optional, default: 50): Max videos to scrape (1-200)
• fetch_contacts (optional, default: true): Whether to fetch contact info

Response:

json

{
  "job_id": "abc123",
  "status": "queued",
  "keyword": "peptides",
  "estimated_seconds": 105
}

Step 2: Poll Job Status#

bash

curl "${KOLENS_API_URL}/api/jobs/[JOB_ID]" \
  -H "Authorization: Bearer ${KOLENS_API_KEY}"

Status values: queued → running → completed | failed

Completed response:

json

{
  "job_id": "abc123",
  "status": "completed",
  "stage": "Done — 12 videos, 8 KOLs, 0 Sellers",
  "progress": 100,
  "total_videos": 12,
  "kol_count": 8,
  "seller_count": 0
}

Step 3: Query KOL List#

bash

# KOLs with email only
curl "${KOLENS_API_URL}/api/kols?keyword=[KEYWORD]&require_email=true&per_page=30" \
  -H "Authorization: Bearer ${KOLENS_API_KEY}"

# All KOLs
curl "${KOLENS_API_URL}/api/kols?keyword=[KEYWORD]&per_page=30" \
  -H "Authorization: Bearer ${KOLENS_API_KEY}"

Response:

json

{
  "total": 6,
  "page": 1,
  "per_page": 30,
  "kols": [
    {
      "username": "somekol",
      "display_name": "Some KOL",
      "follower_count": 1000000,
      "avg_views": 500000,
      "avg_engagement_rate": 0.05,
      "has_email": true,
      "has_website": true,
      "first_seen_at": "2026-04-10T07:18:59.933946",
      "last_updated_at": "2026-04-10T07:18:59.933948"
    }
  ]
}

Step 4: Get Single KOL Profile#

bash

curl "${KOLENS_API_URL}/api/kols/[USERNAME]" \
  -H "Authorization: Bearer ${KOLENS_API_KEY}"

Response:

json

{
  "username": "somekol",
  "display_name": "Some KOL",
  "follower_count": 1000000,
  "avg_views": 500000,
  "avg_engagement_rate": 0.05,
  "bio": "This is my bio",
  "contact": {
    "email": "contact@example.com",
    "phone": null,
    "website": "https://example.com",
    "instagram": "@somekol",
    "youtube": "somekol",
    "linktree_url": "https://linktr.ee/somekol"
  }
}

API Endpoints#

EndpointMethodDescription/api/scrapePOSTSubmit a scraping job/api/jobs/{job_id}GETGet job status/api/kolsGETQuery KOL database/api/kols/{username}GETGet single KOL profile

Workflow Example#

bash

# 1. Submit job
curl -s -X POST "${KOLENS_API_URL}/api/scrape" \
  -H "Authorization: Bearer ${KOLENS_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"keyword":"camping","max_videos":30,"fetch_contacts":true}' > /tmp/job.json

JOB_ID=$(cat /tmp/job.json | jq -r '.job_id')
echo "Job ID: ${JOB_ID}"

# 2. Poll until completed (every 90s)
for i in 1 2 3 4 5 6 7 8 9 10; do
  STATUS=$(curl -s "${KOLENS_API_URL}/api/jobs/${JOB_ID}" \
    -H "Authorization: Bearer ${KOLENS_API_KEY}" | jq -r '.status')
  echo "Status: ${STATUS}"
  if [ "${STATUS}" = "completed" ]; then
    echo "Job completed!"
    break
  fi
  sleep 90
done

# 3. Get KOLs with email
curl -s "${KOLENS_API_URL}/api/kols?keyword=camping&require_email=true" \
  -H "Authorization: Bearer ${KOLENS_API_KEY}"

Troubleshooting#

• Task stuck in "running": The scraping typically takes 2-3 minutes. Continue polling.
• "Invalid or inactive API key": Your API key may have expired. Contact the KOLens admin for a new one.
• Empty results: Try different/ broader keywords, or check if TikTok has content for that keyword.
• Rate limiting: If you get rate limited, wait before making more requests.

Legal Notice#

When using this skill to collect KOL contact information:

• Only use scraped data for legitimate outreach and collaboration purposes
• Respect privacy regulations (GDPR, CCPA, etc.) applicable in your jurisdiction
• Do not use scraped data for spam or unsolicited marketing
• Always verify contact information before reaching out