API
Everything the site does is available over HTTPS with an API key. Searches use your plan the same way as on the site. Create a key on your account page and send it as a Bearer token.
1. Start a search
curl -X POST https://zarlana.com/api/runs \
-H "Authorization: Bearer tcl_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"platform": "youtube", "searchKeywords": ["dog grooming"], "minFollowers": 5000, "maxFollowers": 100000, "region": "US", "maxResults": 50}'
Returns 202 with {"runId": "…", "reserved": 50}. The search holds maxResults creators from your plan and returns the ones it doesn't use when it ends.
| Field | Type | Meaning |
|---|---|---|
platform | string | tiktok (default), instagram or youtube. One search covers one platform. |
searchKeywords | string[] | Niches, topics or hashtags, up to 20. |
handles | string[] | Usernames or profile links (YouTube: channel links or @handles), up to 200. Use this or searchKeywords, or both. |
minFollowers, maxFollowers | integer | Follower range (subscribers on YouTube). |
languages | string[] | TikTok only: account language codes, such as en or es. |
region | string | YouTube only: the country YouTube search runs from, such as US or GB. Default US. |
countries | string[] | YouTube only: keep channels whose About page names one of these countries, such as "United States". |
maxResults | integer | Creators with an email to find, 1 to 500. Default 25. |
enrichBioLinks | boolean | Read link-in-bio pages (YouTube: the channel's website) for more emails and socials. Default true. |
2. Check on it
curl https://zarlana.com/api/runs/RUN_ID -H "Authorization: Bearer tcl_YOUR_KEY"
Poll every 10 seconds or so. When terminal is true, rows is the number of creators found, charged how many came off your plan and alreadyOwned how many you already had.
3. Get the creators
curl https://zarlana.com/api/runs/RUN_ID/results -H "Authorization: Bearer tcl_YOUR_KEY" curl https://zarlana.com/api/runs/RUN_ID/csv -H "Authorization: Bearer tcl_YOUR_KEY" -o creators.csv
Each creator has a platform and a key such as instagram:name or youtube:UC…; username is the handle shown. All creators you ever unlocked: GET /api/creators (JSON) or /api/creators?format=csv, with &platform=youtube to keep one platform. Your plan and creators left: GET /api/me.
Errors
400 bad input, 401 missing or wrong key, 402 not enough creators left on your plan, 429 too many searches running (2 at a time), 502 the search service is busy, try again later. Error bodies are {"error": "…"}.