TikTok Lead Finder

Overview

Build a TikTok lead list in one call. Give accounts of your niche as seed_usernames and/or niche terms as keywords, a follower band and a credit budget; the run does the sourcing itself and returns accounts inside the band with their bio link, Instagram handle and the email from the bio where the account lists one.

How the sourcing works

Accounts of one niche follow each other. The run reads the accounts your seeds follow, keeps the ones inside the follower band, reads their full profile, and then reads the accounts those leads follow (a snowball). Measured on TikTok, following pages bring 23 to 27 leads per 100 lookups, the user search 1 to 3, so the keyword search mainly supplies starting accounts. Seeds give the best yield; seeds themselves are never returned as leads.

A candidate whose follower count is already outside the band, or a private account, is skipped without a lookup.

When to use

Find creators, shops or coaches of a niche with 5,000 to 200,000 followers in DE, AT and CH.
Start from a handful of accounts you know and let the run widen the list.
Combine with require_contact to keep only accounts with an email, a bio link or an Instagram handle.

Endpoint

Input

Output

stopped_because tells why the run ended: limit_reached, budget_exhausted (raise max_credits or start again with the found leads as seeds), time_limit (ten minutes), no_more_candidates or source_error. With source_error a lookup failed after leads had been found: the run completes with those leads and the failed lookup is not billed. When a lookup fails before any lead was found, the run fails and the whole reservation is refunded.

Pricing

Every lookup the run makes (search page, following page, profile) costs 2 credits, also when it comes from our cache. max_credits (default 100) is reserved up front and is the cap: the run stops before a lookup would cross it, and only the lookups made are billed.

Examples

Playground

States

State	Description
`queued`	Request accepted; waiting to be picked up by a worker.
`processing`	Worker is actively running the enrichment.
`completed`	Enrichment finished and results are available in `output`.
`failed`	Enrichment failed; reason is in `error`. Credits are refunded for failures.

Errors

Error	When it happens	What to do
`invalid_input`	Neither `keywords` nor `seed_usernames` given, a handle is malformed, or `max_followers` is below `min_followers`.	Fix the request payload and retry.
`rate_limited`	The platform throttled the lookup. The run goes back to the queue and continues by itself.	No action.
`provider_error`	The data source returned an unexpected error before any lead was found. The run fails and is refunded; after the first lead the run completes with `source_error` instead.	Retry later; if persistent, contact support.
`503 endpoint_unavailable`	The endpoint is currently not configured. Nothing is reserved or charged.	Retry later; if persistent, contact support.