Find creators for a campaign in one country
Search TikTok, Instagram and YouTube for creators in one market above a follower floor, priced first with a free dry run, and keep each one once
Send your topic, your market and a follower floor, and get back a shortlist of creators who post about it. You price the search first for free, then run it with a cap it cannot pass. The example looks for UK creators who post about home espresso.
Measured on 18/11/2026: one run delivered 5 creators based in the UK, one on YouTube and four on TikTok, for 38 credits. It ran 12 searches and looked up the creators it kept.
Start in five minutes
Set your key once. Every block on this page reads it.
export SOCIALCRAWL_API_KEY=YOUR_API_KEYPaste this prompt into your coding agent:
Read https://www.socialcrawl.dev/docs/recipes/campaign-creators.md and follow it to find UK creators who post about home espresso, with at least 10,000 followers. Use the key in SOCIALCRAWL_API_KEY. Price the search with a dry run first (dry_run=true, which is free), and show me the estimate. Then run it with max_credits=60 and never raise the cap without asking me.Or price it yourself. A dry run plans the search and quotes it for 0 credits:
curl -G "https://www.socialcrawl.dev/v1/prism/creators" \
-H "x-api-key: $SOCIALCRAWL_API_KEY" \
--data-urlencode "keywords=home espresso,latte art" \
--data-urlencode "platforms=tiktok,instagram,youtube" \
--data-urlencode "country=GB" \
--data-urlencode "min_followers=10000" \
--data-urlencode "limit=5" \
--data-urlencode "depth=quick" \
--data-urlencode "label=none" \
--data-urlencode "max_credits=60" \
--data-urlencode "format=compact" \
--data-urlencode "dry_run=true"On 18/11/2026 it quoted about 57 credits, at most 60, and said 57 is the least max_credits it accepts.
How it works
- Your topic words run as a search on each platform, and as an account search where the platform has one.
- Each creator found is looked up once, so the follower floor and the country are checked on the profile.
- The run works in the background and stops at
max_credits. It never spends more. - You follow the run until it ends, then read the creators page by page.
- You store each creator once and report only the ones you have not seen.
What you need
| Call | What it gives | Credits |
|---|---|---|
GET /v1/prism/creators | The creators, run in the background | Each search at its own price, 1 a profile lookup, up to max_credits |
The same call with dry_run=true | The plan and the price | 0 |
The run's status_url | Progress, then the creators | 0 |
Steps
Step 1: run it with a cap
Send the same request without dry_run. It answers 202 at once with the run.
curl -G "https://www.socialcrawl.dev/v1/prism/creators" \
-H "x-api-key: $SOCIALCRAWL_API_KEY" \
--data-urlencode "keywords=home espresso,latte art" \
--data-urlencode "platforms=tiktok,instagram,youtube" \
--data-urlencode "country=GB" \
--data-urlencode "min_followers=10000" \
--data-urlencode "limit=5" \
--data-urlencode "depth=quick" \
--data-urlencode "label=none" \
--data-urlencode "max_credits=60" \
--data-urlencode "format=compact"import json, os, urllib.parse, urllib.request
params = {"keywords": "home espresso,latte art", "platforms": "tiktok,instagram,youtube",
"country": "GB", "min_followers": "10000", "limit": "5", "depth": "quick",
"label": "none", "max_credits": "60", "format": "compact"}
url = "https://www.socialcrawl.dev/v1/prism/creators?" + urllib.parse.urlencode(params)
req = urllib.request.Request(url, headers={"x-api-key": os.environ["SOCIALCRAWL_API_KEY"]})
answer = json.load(urllib.request.urlopen(req, timeout=120))
print(answer["data"]["run"]["status"], answer["data"]["next"]["status_url"])country=GBruns a localised search on TikTok. On Instagram and YouTube the search runs as sent, and creators are kept by the country on their profile. The dry run says so in_warnings.depth=quickreads each creator's profile and skips the walk through their posts.label=noneturns judging off. Judging scores how well each creator fits your topic, and it is the largest part of the price.- Sending the same request again while the run exists returns that run, at no extra cost.
Step 2: follow the run and read the creators
Call data.next.status_url until data.run.status is no longer queued or running. Reading a run is free.
import json, os, time, urllib.request
STATUS_URL = os.environ["STATUS_URL"] # data.next.status_url from step 1
req = urllib.request.Request(STATUS_URL, headers={"x-api-key": os.environ["SOCIALCRAWL_API_KEY"]})
answer = json.load(urllib.request.urlopen(req, timeout=120))
while answer["data"]["run"]["status"] in ("queued", "running"):
time.sleep(5)
answer = json.load(urllib.request.urlopen(req, timeout=120))
for c in answer["data"]["items"]:
print(c["platform"], c.get("username"), c.get("followers"))curl -sS "$STATUS_URL" -H "x-api-key: $SOCIALCRAWL_API_KEY"{
"data": {
"run": {
"status": "partial",
"stopped_because": "max_credits",
"credits": { "spent": 38 }
},
"items": [
{
"key": "youtube:UCMb0O2CdPBNi-QqPk5T3gsQ",
"platform": "youtube",
"username": "jameshoffmann",
"followers": 2570000,
"country": "GB",
"why": { "matched_filters": ["country=GB", "min_followers=10000"] }
}
]
}
}partial with stopped_because: max_credits means the run kept your 5 creators and left the rest of its candidates unread. Its next_step says how to resume it with a higher cap, and a resume bills only the work not yet done.
Store only what is new
Key each creator on key, its platform and account id, such as youtube:UCMb0O2CdPBNi-QqPk5T3gsQ. A creator already in your table is not new, even when a later run finds them again. Store the follower count with the date, so a later run shows who grew. To keep a creator out of every later run, send their account key in exclude.
What it costs
| Part | Credits |
|---|---|
| The dry run | 0 |
| Each platform search that returns rows | That platform's own search price |
| Each creator's profile lookup | 1 (5 on LinkedIn) |
| Judging, when it is on | 1 per started 5 creators per pass |
| Reading the run | 0 |
What the example run measured on 18/11/2026:
| Run | Creators | Credits |
|---|---|---|
| The dry run | 0 | 0 |
The run, limit=5, max_credits=60 | 5 | 38 |
| The full program straight after, the same request | the same 5 | 0 |
The second request found the first run still open and returned it, so it cost nothing.
Tips, and what not to use
- Price judging before you turn it on. On this request the dry run quoted about 57 credits without judging and about 661 with it, for the same 5 creators.
- The run stops at
max_creditsand pauses there. It never overspends, and amorecall can raise the cap later. - Raise
limitfor a longer list. The dry run prices each step, so price again after every change. - A search that fails, finds nothing or is served from cache costs 0.
- Do not use
GET /v1/prism/discoverwithview=accountsfor creators. It still works, and it is the right call for shops and sellers. For creators, this call is the one to use.
