# Campaign creators (/docs/recipes/campaign-creators) 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. ```bash title="Terminal" export SOCIALCRAWL_API_KEY=YOUR_API_KEY ``` Paste this prompt into your coding agent: ```text title="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: ```bash title="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 | 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** ```bash title="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** ```python title="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** ```python title="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** ```bash title="Terminal" curl -sS "$STATUS_URL" -H "x-api-key: $SOCIALCRAWL_API_KEY" ``` ```json title="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 | 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_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 **Full program (Python)** ```python title="Python" # campaign_creators.py: a shortlist of creators in one country, each kept once. # Run: SOCIALCRAWL_API_KEY=... python3 campaign_creators.py (Python 3.9+, nothing to install) import json import os import sqlite3 import time import urllib.parse import urllib.request KEY = os.environ["SOCIALCRAWL_API_KEY"] BASE = "https://www.socialcrawl.dev/v1" SEARCH = { "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", } def call(url): req = urllib.request.Request(url, headers={"x-api-key": KEY}) with urllib.request.urlopen(req, timeout=120) as res: return json.load(res) # 1. Price it. A dry run is free and says the least max_credits it accepts. quote = call(f"{BASE}/prism/creators?" + urllib.parse.urlencode({**SEARCH, "dry_run": "true"})) print("estimate:", quote["data"]["estimate"]["credits"]) # 2. Start it, then follow the run until it ends. answer = call(f"{BASE}/prism/creators?" + urllib.parse.urlencode(SEARCH)) while answer["data"]["run"]["status"] in ("queued", "running"): time.sleep(5) answer = call(answer["data"]["next"]["status_url"]) run = answer["data"]["run"] creators = list(answer["data"]["items"]) cursor = (answer.get("pagination") or {}).get("next_cursor") while cursor: page = call(f"{BASE}/prism/creators/runs/{run['run_id']}?" + urllib.parse.urlencode({"format": "compact", "cursor": cursor})) creators.extend(page["data"]["items"]) cursor = (page.get("pagination") or {}).get("next_cursor") # 3. Store each creator once, keyed on its account key (platform:account id). db = sqlite3.connect("creators.db") db.execute("CREATE TABLE IF NOT EXISTS creators (key TEXT PRIMARY KEY, platform TEXT, username TEXT, followers INTEGER, first_seen TEXT)") new = 0 for c in creators: cur = db.execute("INSERT OR IGNORE INTO creators VALUES (?, ?, ?, ?, date('now'))", (c["key"], c["platform"], c.get("username"), c.get("followers"))) new += cur.rowcount print(f"{c['platform']:9} @{c.get('username')} {c.get('followers')} followers") db.commit() print(f"{len(creators)} creators, {new} new; run {run['status']}, {run['credits']['spent']} credits") ``` **Agent brief** ```text title="Agent brief" Goal: a shortlist of UK creators who post about home espresso, with at least 10,000 followers, each stored once. Read https://www.socialcrawl.dev/docs/recipes/campaign-creators.md first. 1. Send GET /v1/prism/creators with the page's parameters and dry_run=true. Show me data.estimate.credits. 2. Run it with max_credits=60. Never raise max_credits without asking me. 3. Follow data.next.status_url until data.run.status is no longer queued or running. 4. Store each creator by its key. Report only new ones, with their follower counts. ``` ## Next steps - [Follow creators](/docs/recipes/follow-creators.md): Get only the new posts of the creators on your list. - [Creator search](/docs/prism/creators.md): Every parameter of the creator search, with its price. - [Credits](/docs/credits.md): What a call costs and what is never charged.