TikTok Account Validation

An Apify Actor built in TypeScript with the Apify SDK and Crawlee that validates TikTok accounts and returns their status (active, private, not_found, banned, or unknown) along with profile metrics.

Features & Scope

Given one or more TikTok usernames, the Actor determines whether each account exists and extracts basic profile data:

• username — Normalized TikTok username (lowercase, stripped of leading @)
• exists — true if the account exists, false if not found, or null if status cannot be determined
• accountStatus — Account classification:
  • "active" — The profile exists, is publicly accessible, and profile metadata is available.
  • "private" — The profile exists and is set to private (isPrivate: true). Basic header counts (followers, following, likes, videos) are included when public.
  • "not_found" — The account does not exist or has been deleted (exists: false).
  • "banned" — The account has been suspended or is unavailable due to policy/legal restrictions.
  • "unknown" — The account status could not be classified (e.g. invalid input format or unexpected page structure).
• isPrivate — true if private, false if public, null if not found or unknown
• isVerified — true if verified with blue checkmark, false otherwise, null if not found or unknown
• isBusinessAccount — true if registered as a TikTok business/commerce/seller account
• nickname — Profile display name
• followersCount — Number of followers (null if not found or unknown)
• followingCount — Number of accounts followed (null if not found or unknown)
• likesCount — Total likes (hearts) received across all videos
• videosCount — Total number of published videos
• profileUrl — Canonical profile URL (https://www.tiktok.com/@<username>)
• checkedAt — ISO 8601 timestamp of validation
• error — Error description if validation failed or input was invalid, otherwise null

Strict Scope Guarantees

• Usernames only: URLs are not accepted in this version.
• No fabricated numbers: Any metric that cannot be read publicly returns null — values are never guessed.
• Every input accounted for: Invalid usernames or missing accounts produce a structured dataset item with a descriptive error field without crashing the run.

---

Input

The Actor input is defined in ./.actor/input_schema.json and ./INPUT_SCHEMA.json:

Field	Type	Required	Default	Description
usernames	string[]	Yes	—	One or more TikTok usernames (e.g. "tiktok", "@tiktok").
proxyConfiguration	object	No	{ "useApifyProxy": true }	Apify Proxy configuration. Residential proxies recommended if plain requests are blocked.
maxConcurrency	integer	No	4	Number of accounts processed in parallel (1–10).
sessionCookie	string (secret)	No	—	Optional TikTok sessionid cookie value if authenticated access is needed.

Example Input

{
    "usernames": [
        "tiktok",
        "private",
        "user_nonexistent_9988776655443322",
        "bad username!"
    ],
    "proxyConfiguration": {
        "useApifyProxy": true
    },
    "maxConcurrency": 4
}

---

Output

The Actor pushes one dataset item per input username in the default Apify Dataset, rendered as a table in the Apify Console.

Output Schema

{
    "username": "string",
    "exists": "boolean | null",
    "accountStatus": "active | private | not_found | banned | unknown",
    "isPrivate": "boolean | null",
    "isVerified": "boolean | null",
    "isBusinessAccount": "boolean | null",
    "nickname": "string | null",
    "followersCount": "number | null",
    "followingCount": "number | null",
    "likesCount": "number | null",
    "videosCount": "number | null",
    "profileUrl": "string",
    "checkedAt": "ISO 8601 string",
    "error": "string | null"
}

Example Output

[
    {
        "username": "tiktok",
        "exists": true,
        "accountStatus": "active",
        "isPrivate": false,
        "isVerified": true,
        "isBusinessAccount": true,
        "nickname": "TikTok",
        "followersCount": 96300000,
        "followingCount": 1,
        "likesCount": 465800000,
        "videosCount": 1512,
        "profileUrl": "https://www.tiktok.com/@tiktok",
        "checkedAt": "2026-10-19T06:00:00.000Z",
        "error": null
    },
    {
        "username": "private",
        "exists": true,
        "accountStatus": "private",
        "isPrivate": true,
        "isVerified": false,
        "isBusinessAccount": false,
        "nickname": "private",
        "followersCount": 2,
        "followingCount": 3,
        "likesCount": 0,
        "videosCount": 0,
        "profileUrl": "https://www.tiktok.com/@private",
        "checkedAt": "2026-10-19T06:00:01.000Z",
        "error": null
    },
    {
        "username": "user_nonexistent_9988776655443322",
        "exists": false,
        "accountStatus": "not_found",
        "isPrivate": null,
        "isVerified": null,
        "isBusinessAccount": null,
        "nickname": null,
        "followersCount": null,
        "followingCount": null,
        "likesCount": null,
        "videosCount": null,
        "profileUrl": "https://www.tiktok.com/@user_nonexistent_9988776655443322",
        "checkedAt": "2026-10-19T06:00:02.000Z",
        "error": null
    },
    {
        "username": "bad username!",
        "exists": null,
        "accountStatus": "unknown",
        "isPrivate": null,
        "isVerified": null,
        "isBusinessAccount": null,
        "nickname": null,
        "followersCount": null,
        "followingCount": null,
        "likesCount": null,
        "videosCount": null,
        "profileUrl": "https://www.tiktok.com/@bad username!",
        "checkedAt": "2026-10-19T06:00:00.000Z",
        "error": "Invalid TikTok username: usernames may only contain letters, numbers, underscores, and periods."
    }
]

---

Status Meanings

Status	Meaning	exists	Metrics Available
active	Public, active TikTok account	true	Yes (followers, following, likes, videos, verified, business, nickname)
private	Private TikTok account	true	Header metrics available from public page
not_found	Account does not exist or was deleted	false	null
banned	Account suspended or banned for policy/legal reasons	true	null
unknown	Unclassified page or invalid input format	null	null

---

Local Development & Testing

# Install dependencies
npm install

# Run unit tests
npm test

# Build TypeScript
npm run build

# Run Actor locally using Apify CLI
apify run

---

Deployment to Apify Platform

# 1. Authenticate with your Apify account
apify login

# 2. Deploy the Actor to the Apify platform
apify push

---

Summary of Testing

• active: Confirmed on public accounts (e.g. @tiktok, @john), extracting complete metrics (followersCount, followingCount, likesCount, videosCount, isVerified, isBusinessAccount).
• private: Confirmed on private accounts (e.g. @private, @secret), detecting isPrivate: true and extracting public header metrics.
• not_found: Confirmed on non-existent usernames (e.g. @user_nonexistent_9988776655443322), returning exists: false with null metrics.
• banned: Confirmed on suspended/banned status codes (209002, 10223) and page messages.
• unknown: Used when requests fail after all retries or when input usernames are invalid (e.g. spaces, special characters, length > 24, or URLs).