API documentation

1. Quickstart

From account to first response in 3 steps.

curl "https://api.sociallens.dev/v1/ping" \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

Expected response: {"ok":true,"user_id":123}. From there, swap /v1/ping for the endpoint you need.

curl "https://api.sociallens.dev/v1/profile?username=exemplo&platform=tiktok" \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

2. Authentication

Every call to /v1/* carries the key in the Authorization header, Bearer format. The key never goes in the URL, so it never leaks into proxy logs or browser history.

Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Getting a key

Signed in, open /keys and generate a key with a name (e.g. "production", "staging"). You can have up to 10 active keys at once, one per environment or app. We store only the hash: a lost key cannot be recovered, only replaced.

Revoking

Same screen, "Revoke". The key stops working instantly and any call using it gets 401 invalid_token. Revoking does not affect your credits or your other keys.

A missing, wrong or revoked key always gets the same body:

{ "error": "invalid_token", "message": "API key missing, invalid or revoked." }

3. Endpoints

Base URL: https://api.sociallens.dev. Every response is UTF-8 JSON. The schema is the same for all platforms: change platform and the fields stay the same.

Public profile

Reads a user's public profile and returns normalized counters and identity.

Example request

curl "https://api.sociallens.dev/v1/profile?username=exemplo&platform=tiktok" \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

Example response 200

{
  "username":   "exemplo",
  "platform":   "tiktok",
  "nickname":   "Exemplo Oficial",
  "verified":   true,
  "followers":  1284310,
  "following":  212,
  "likes":      48210933,
  "videos":     431,
  "bio":        "Content creator. Contact in bio.",
  "avatar":     "https://.../avatar.jpg",
  "fetched_at": "2026-11-07T12:02:15Z",
  "credits":    { "source": "paid", "charged": 1, "balance": 7999 }
}

Response fields

During the beta the response may include an extra informational note field. Ignore it in your parser; it goes away in the stable version.

Followers of a profile (paginated)

Lists a profile's public followers, one page per call. For the next page, repeat the call with the previous next_cursor. Each page costs 1 credit regardless of how many followers it contains.

curl "https://api.sociallens.dev/v1/followers?username=exemplo&platform=tiktok" \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

{
  "username":    "exemplo",
  "platform":    "tiktok",
  "followers": [
    { "username": "exemplo_um",   "nickname": "Exemplo Um",   "verified": false, "avatar": "https://..." },
    { "username": "exemplo_dois", "nickname": "Exemplo Dois", "verified": true,  "avatar": "https://..." }
  ],
  "next_cursor": "c2VndWludGU6MjA",
  "fetched_at":  "2026-11-07T12:02:15Z",
  "credits":     { "source": "paid", "charged": 1, "balance": 7998 }
}

Fake follower estimate

Estimates the percentage of fake or bot followers of a profile from a sample of its followers. Costs more than a simple read because it analyzes several profiles per call. Ideal for vetting an influencer before a campaign, or for audit tools.

curl "https://api.sociallens.dev/v1/bot-estimate?username=exemplo&platform=tiktok" \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

{
  "username":       "exemplo",
  "platform":       "tiktok",
  "bot_score":      23,
  "classification": "low",
  "sample_size":    200,
  "fetched_at":     "2026-11-07T12:02:15Z",
  "credits":        { "source": "paid", "charged": 5, "balance": 7993 }
}

Ping (key check)

Consumes no credit and does not count toward the data rate limit. Returns {"ok":true,"user_id":N} when the key is valid.

Coming next

• GET /v1/posts: latest posts of a profile with views, likes and comments.

4. Credits and cost

• Cost per endpoint, shown next to each one on this page and returned in credits.charged: /v1/profile 1, /v1/followers 1 per page, /v1/bot-estimate 5. On the trial, each call deducts its cost from the daily quota.
• Free trial on sign-up: 100 requests a day for 14 days, no card. The daily counter resets at midnight UTC (resets_at gives the exact time). Over the day: 402 daily_trial_limit. After the 14 days: 402 trial_expired.
• Paid credits never expire and have no daily limit. When you have a paid balance it is used first; the trial only kicks in when the paid balance is zero. Packs: Starter US$ 19 = 8,000 · Pro US$ 79 = 40,000 · Scale US$ 299 = 180,000. Buy at /credits; details at /pricing.
• The credits block of every response says where the request came from (source: "paid" or "trial") and, on the trial, how much of the day is used.

Every refund is recorded in your statement with the same reference as the charge, so it can be audited.

5. Rate limit

Each key is limited to 60 requests per minute on data endpoints. The limit is per key, not per account: two keys, two limits.

Over the limit, the API answers 429 rate_limited, charges nothing, and tells you how long to wait:

HTTP/1.1 429 Too Many Requests
Retry-After: 41

{
  "error": "rate_limited",
  "message": "Too many requests. Wait and try again.",
  "retry_after": 41,
  "limit_per_min": 60
}

The Retry-After header and the retry_after field give the seconds until the window opens again. Sleep that long and retry; no exponential backoff needed. Need more volume? Reach us at /contact.

6. Errors

Every error has the same shape, always JSON: {"error": "<code>", "message": "..."}. The code is stable (use it in your switch); the message is for humans and may change.

Non-existent or private profiles are being defined together with the reading engine and will get their own code before the stable version. Until then they fall under source_unavailable, never charged.

7. Code examples

The same call in three languages. Replace sk_live_YOUR_KEY with your key. In production, read the key from an environment variable; do not hardcode it.

curl "https://api.sociallens.dev/v1/profile?username=exemplo&platform=tiktok" \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

import os, time, requests

API_KEY = os.environ.get("SOCIALDATA_KEY", "sk_live_YOUR_KEY")
BASE = "https://api.sociallens.dev"

def profile(username, platform="tiktok"):
    r = requests.get(
        f"{BASE}/v1/profile",
        params={"username": username, "platform": platform},
        headers={"Authorization": f"Bearer {API_KEY}"},
        timeout=15,
    )
    if r.status_code == 429:
        time.sleep(int(r.headers.get("Retry-After", 5)))
        return profile(username, platform)
    data = r.json()
    if r.status_code != 200:
        raise RuntimeError(f"{data['error']}: {data['message']}")
    return data

p = profile("exemplo")
print(p["followers"], "followers · balance", p["credits"]["balance"])

const API_KEY = process.env.SOCIALDATA_KEY ?? "sk_live_YOUR_KEY";
const BASE = "https://api.sociallens.dev";

async function profile(username, platform = "tiktok") {
  const url = `${BASE}/v1/profile?` + new URLSearchParams({ username, platform });
  const res = await fetch(url, { headers: { Authorization: `Bearer ${API_KEY}` } });
  if (res.status === 429) {
    const wait = Number(res.headers.get("Retry-After") ?? 5);
    await new Promise(r => setTimeout(r, wait * 1000));
    return profile(username, platform);
  }
  const data = await res.json();
  if (!res.ok) throw new Error(`${data.error}: ${data.message}`);
  return data;
}

const p = await profile("exemplo");
console.log(p.followers, "followers · balance", p.credits.balance);