SocialCrawl
Cookbooks

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.

Terminal
export SOCIALCRAWL_API_KEY=YOUR_API_KEY

Paste this prompt into your coding agent:

Prompt
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
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

CallWhat it givesCredits
GET /v1/prism/creatorsThe creators, run in the backgroundEach search at its own price, 1 a profile lookup, up to max_credits
The same call with dry_run=trueThe plan and the price0
The run's status_urlProgress, then the creators0

Steps

Step 1: run it with a cap

Send the same request without dry_run. It answers 202 at once with the run.

cURL
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"
Python
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=GB runs 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=quick reads each creator's profile and skips the walk through their posts.
  • label=none turns 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.

Python
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"))
Terminal
curl -sS "$STATUS_URL" -H "x-api-key: $SOCIALCRAWL_API_KEY"
Response (trimmed)
{
  "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

PartCredits
The dry run0
Each platform search that returns rowsThat platform's own search price
Each creator's profile lookup1 (5 on LinkedIn)
Judging, when it is on1 per started 5 creators per pass
Reading the run0

What the example run measured on 18/11/2026:

RunCreatorsCredits
The dry run00
The run, limit=5, max_credits=60538
The full program straight after, the same requestthe same 50

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_credits and pauses there. It never overspends, and a more call can raise the cap later.
  • Raise limit for 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/discover with view=accounts for creators. It still works, and it is the right call for shops and sellers. For creators, this call is the one to use.

Full program and agent brief

Next steps