# Creators quickstart (/docs/prism/creators-quickstart) Price a creator search for free, run it, read the creators it returns, then narrow it by market, size and views Creator search finds the creators who post about your topic, measures each one from its recent posts, and ranks them with the reasons. This page takes you from no key to a ranked list in four steps, then shows how to ask for a thousand creators and the fields you will add next. ## 1. Get your API key New accounts get 100 credits on signup and no card is needed. The five-creator search in steps 2 to 4 costs about 40 credits. The thousand-creator search in step 5 costs far more, and its own dry run prices it first. Get a free API key at https://www.socialcrawl.dev/dashboard/api. New accounts start with 100 welcome credits and no card is needed. ## 2. Price the search for free Add `dry_run=true` to any request. It costs nothing, starts nothing, and tells you what the real call will do. ```bash title="cURL" curl "https://www.socialcrawl.dev/v1/prism/creators?keywords=home+espresso&platforms=tiktok,instagram&min_followers=10000&limit=5&max_credits=100&deadline_s=60&dry_run=true" \ -H "x-api-key: YOUR_API_KEY" ``` ```json title="Response (trimmed)" { "success": true, "data": { "estimate": { "total": { "min": 15, "expected": 42, "max": 2272 }, "per_delivered": { "min": 3, "expected": 8.4, "max": 454.4 }, "answers_in_call": true }, "next_step": "Send the same request without dry_run to run it; it answers in this call and is expected to cost about 42 credits (about 8.4 a creator, at most 2272 in all, never past max_credits=100)." }, "credits_used": 0 } ``` The request asks for 5 creators who post about home espresso on TikTok and Instagram, each with at least 10,000 followers. `answers_in_call: true` means the creators come back in the same response. The run never spends more than `max_credits`. A GET's default is 200, and a call that answers in the response first holds up to that cap from your balance, so this request sends `max_credits=100`, which a new account's 100 credits cover. ## 3. Run it Send the same request without `dry_run`. ```bash title="cURL" curl "https://www.socialcrawl.dev/v1/prism/creators?keywords=home+espresso&platforms=tiktok,instagram&min_followers=10000&limit=5&max_credits=100&deadline_s=60" \ -H "x-api-key: YOUR_API_KEY" ``` ```json title="Response (one creator, trimmed)" { "success": true, "data": { "items": [ { "account": { "key": "tiktok:alexhomebarista", "display_name": "Alex Home Barista", "followers": 238562, "url": "https://www.tiktok.com/@alexhomebarista", "country": { "value": "US", "name": "United States", "source": "author_declared", "confidence": 0.9 }, "metrics": { "median_views": 17212, "engagement_rate": 0.073926, "posts_per_week": 5.24, "posts_used": 12 } }, "judgments": { "fit": { "p": 0.98 }, "account_kind": "individual_creator" }, "score": { "value": 0.74, "components": { "fit": 0.98, "engagement": 0.3577, "activity": 0.5829, "reach": 1 } }, "why": { "matched_filters": [{ "field": "min_followers", "value": 10000, "measured": 238562 }], "judgment_basis": "evidence and 12 walked captions" } } ], "run": { "run_id": "run_NnUfcuc8bLFekvPYGnfJZx", "status": "completed", "credits": { "spent": 32 } } } } ``` That call answered in 38 seconds with 5 creators for 32 credits. In that time it: - searched TikTok and Instagram for posts and accounts about "home espresso", and dropped every candidate under 10,000 followers. - read each remaining creator's last 12 posts (pinned posts left out) to measure `median_views`, the views of a typical post, and `engagement_rate`. - judged each creator against your topic (`fit`) and ranked them by `score`, which combines fit, engagement, posting activity and reach. `why` on each creator lists the filters it passed and what its judgment was based on. ## 4. Bigger searches run in the background A search for more creators takes longer than one call can wait. It answers `202` at once with a run, and you poll `data.next.status_url` until `data.run.status` is `completed`. Each poll waits up to 25 seconds for news, so a plain loop is enough. **Python** ```python title="Python" import json, os, urllib.parse, urllib.request KEY = os.environ["SOCIALCRAWL_API_KEY"] BASE = "https://www.socialcrawl.dev" def get(url): request = urllib.request.Request(url, headers={"x-api-key": KEY}) with urllib.request.urlopen(request, timeout=60) as response: return response.read().decode() params = urllib.parse.urlencode({ "keywords": "home espresso,latte art", "platforms": "tiktok,instagram", "min_followers": 10000, "max_followers": 250000, "limit": 50, "max_credits": 500, "format": "compact", }) answer = json.loads(get(f"{BASE}/v1/prism/creators?{params}")) while answer["data"]["run"]["status"] in ("queued", "running"): answer = json.loads(get(answer["data"]["next"]["status_url"])) print(answer["data"]["run"]["next_step"]) # Every creator, one JSON object per line. The last line is {"complete": true}, # or {"next_cursor": ...} when the export continues in another read. results = answer["data"]["next"]["results_url"] + "?format=compact" cursor = None while True: url = results if cursor is None else results + "&cursor=" + urllib.parse.quote(cursor) cursor = None for line in get(url).splitlines(): creator = json.loads(line) if "next_cursor" in creator: cursor = creator["next_cursor"] elif "key" in creator: print(creator.get("score"), creator["platform"], "@" + str(creator.get("username")), creator.get("followers")) if cursor is None: break ``` **TypeScript** ```typescript title="TypeScript" const KEY = process.env.SOCIALCRAWL_API_KEY!; const BASE = "https://www.socialcrawl.dev"; async function get(url: string): Promise { const response = await fetch(url, { headers: { "x-api-key": KEY }, signal: AbortSignal.timeout(60_000) }); return response.text(); } const params = new URLSearchParams({ keywords: "home espresso,latte art", platforms: "tiktok,instagram", min_followers: "10000", max_followers: "250000", limit: "50", max_credits: "500", format: "compact", }); let answer = JSON.parse(await get(`${BASE}/v1/prism/creators?${params}`)); while (["queued", "running"].includes(answer.data.run.status)) { answer = JSON.parse(await get(answer.data.next.status_url)); } console.log(answer.data.run.next_step); // Every creator, one JSON object per line. The last line is {"complete": true}, // or {"next_cursor": ...} when the export continues in another read. const results = `${answer.data.next.results_url}?format=compact`; let cursor: string | null = null; do { const url: string = cursor === null ? results : `${results}&cursor=${encodeURIComponent(cursor)}`; cursor = null; for (const line of (await get(url)).split("\n").filter(Boolean)) { const c = JSON.parse(line); if (c.next_cursor) cursor = c.next_cursor; else if (c.key) console.log(c.score, c.platform, `@${c.username}`, c.followers); } } while (cursor !== null); ``` `data.next.results_url` streams every creator of the run, one JSON object per line, and `format=compact` makes each line one flat row. To page through a run instead, read `GET /v1/prism/creators/runs/{run_id}` (25 creators a page by default, up to 100 with `page_size`) and send back `pagination.next_cursor` as `cursor` while `pagination.has_more` is `true`. Reading a run is free. A run's export can be too long for one read: then its last line is `{"next_cursor": "..."}` instead of `{"complete": true}`. Read `results_url` again with that value as `cursor` (`&cursor=...`) until a read ends with `{"complete": true}`. If the run stops at its `max_credits` cap, its status is `paused` and `next_step` says how many credits finish it. `data.next.resume_url` is a ready call, `{ "method": "POST", "url": ..., "body": ... }`: send a `POST` to `resume_url.url` with `resume_url.body` as the JSON body, and nothing already bought is bought again. When the body carries a higher `max_credits`, that is the new total cap, so ask before you send it. ## 5. Ask for a thousand creators `limit` is a target. A background run keeps reading pages and planning new searches while they still add creators, until it has `limit` creators, its sources run dry, it reaches `max_credits`, or it reaches its safety bound (20 rounds of new searches, page 50 of each search, 6 hours from its latest start), and it says which one happened. Price the run first. The estimate of a large request is the part to read, and the dry run is free. ```bash title="cURL" curl -X POST "https://www.socialcrawl.dev/v1/prism/creators" \ -H "x-api-key: YOUR_API_KEY" \ -H "content-type: application/json" \ -d '{ "keywords": ["fitness coach", "personal trainer"], "platforms": ["tiktok", "instagram"], "country": ["GB"], "min_followers": 10000, "max_followers": 100000, "limit": 1000, "max_credits": 8000, "dry_run": true }' ``` ```json title="Response (trimmed)" { "success": true, "data": { "estimate": { "total": { "min": 2209, "expected": 8000, "max": 8000 }, "per_delivered": { "min": 2.21, "expected": 43.26, "max": 57.28 }, "delivered": { "expected": 126.3, "max": 1000 }, "ratios": { "fitted_at": "28/10/2026", "provisional_since": null, "fill_provisional_since": "03/11/2026" } }, "suggested_max_credits": 54075, "next_step": "Send the same request without dry_run to start it; it runs in the background and answers 202 with the run, is expected to cost up to max_credits=8000, and then data.next.status_url follows it. A run looking for every creator keeps spending while it still finds them, up to max_credits=8000; reaching 1000 is expected to need about 43260 credits (max_credits=54075 leaves room). About 126 creators are expected from the first pages of these searches; the run keeps searching toward 1000, but how many more it finds past the first page is not yet measured, so plan on about 126 and treat 1000 as the most." }, "credits_used": 0 } ``` The figures show the shape; yours come from your own dry run. `estimate.delivered.expected` is how many creators the first pages of the searches are expected to give, the number to plan on. `estimate.delivered.max` is the most the run can reach: `limit`, or fewer when your `max_credits` buys fewer. `estimate.per_delivered.expected` is what one creator is expected to cost (the modelled fill's cost over the creators the first pages are expected to give, before your `max_credits`). How many more the run finds past the first page is not yet measured, so a run can end anywhere up to `delivered.max`, and a narrow niche can end below `delivered.expected`. A run keeps spending while it still finds creators, so `estimate.total.expected` is that per-creator figure times `limit`, never past `max_credits`, and `suggested_max_credits` leaves room for reaching `limit`. When reaching `limit` needs more than the cap, `next_step` says `A run looking for every creator keeps spending while it still finds them, up to max_credits={cap}; reaching {limit} is expected to need about {cost} credits (max_credits={suggested} leaves room).`; within the cap it says `A run looking for every creator keeps spending while it still finds them; reaching {limit} is expected to need about {cost} credits, within max_credits={cap}.`; when the searches are expected to run dry first, it says `These searches may run dry before reaching {limit} creators; a more can look further once the run completes.` `fill_provisional_since` marks the later pages and new searches as estimated rather than measured. Send the same body without `dry_run`. It answers `202` with a run, and you follow `data.next.status_url` as in step 4. When the run is `completed`, read the end of `data.summary`: ```json title="data.summary at the end of a run that fell short (trimmed)" { "delivered": 640, "short_reason": "candidates_exhausted", "pass_rate": null, "more_available": false } ``` `data.run.next_step` says the same in a sentence an agent can relay: "The run is complete: 640 of 1000 creators are here, readable as JSON lines at next.results_url, free", followed by whether more can be found. - `more_available: false` means the run has finished looking. After two rounds of new searches that found no new creators, its `next_step` says "This run has finished: two rounds of new searches found no new creators, so searching further is unlikely to find more. To widen it, start a run with other keywords, platforms or filters." When no new search is left to try, it says "This run has finished: there are no new searches left to try for this request, so searching further is unlikely to find more. To widen it, start a run with other keywords, platforms or filters." - `more_available: true` means more can still be found: the run stopped at its safety bound with work left (its `limits` line names the bound), or it could not plan new searches. POST `data.next.more_url` with the body it carries; add `dry_run: true` to price it first. - `more_available: null` means the run is not a completed short run. It met `limit`, or it paused at `max_credits`, where `data.next.resume_url` is the next call. It is also `null` for a run that measured a list of handles you gave it, which has no searches of its own: its `next_step` says how many handles were kept, and `data.next.more_url` looks for more creators on the same topics as the ones kept. `short_reason` is `low_yield` when the last creators looked up rarely passed your filters; `pass_rate` is then the measured share. A run never spends past `max_credits`: when the cap comes first, the run pauses with `stopped_because: "max_credits"`, the creators found are yours, and `resume_url` carries the higher cap to approve. ## What do I add next? Every field below goes on the same request. Price each change with `dry_run=true` first. | You want | Add | | --- | --- | | Creators in one country | `country=GB` (up to 5 codes) | | A size band | `min_followers=10000&max_followers=250000` | | A floor on typical views | `min_median_views=5000` (the median of each creator's recent posts) | | Individual creators, not brands or fan pages | `account_kind=individual_creator` | | Their public emails and phone numbers | `include=contacts` | | Creators who posted in the last 30 days | `active_within_days=30` | | YouTube, X, LinkedIn, Threads or Facebook too | `platforms=tiktok,instagram,youtube,twitter,linkedin,threads,facebook` | | The whole ask in one sentence | `prompt=UK fitness coaches on TikTok with 20k to 200k followers&max_credits=100`, then read `data.request.compiled`. It always answers `202` and continues in the background, so follow `data.next.status_url` as in step 4. | | More creators like one you know | `similar_to=tiktok:liahyoo` in place of `keywords` | Three requests are sent as `POST /v1/prism/creators` with a JSON body. All three are in [Creator search](/docs/prism/creators.md#canonical-requests): - **Creators for a product.** Use `campaign` to describe the product and who it is for. The search works out the topics its buyers watch. - **Measure creators you already have.** Send up to 1,000 `handles` with `purpose: "creator"`, and every handle comes back measured and ranked. - **New creators every week.** Add `schedule`, and the same search runs again and reports only creators it has not delivered before. ## What does it cost? Each search, profile lookup and post read is billed at its own published price, with no surcharge, and a run never spends more than `max_credits`. Dry runs, refusals, reading a run and sending the same request again within 24 hours cost nothing. See [what each step costs](/docs/prism/creators.md#what-it-costs). ## Using an AI agent? Give your agent the three creator tools, fetched as JSON with no key: [`socialcrawl_find_creators`](/agent-tools/socialcrawl_find_creators.json) starts a search, [`socialcrawl_creators_run`](/agent-tools/socialcrawl_creators_run.json) waits on, reads and resumes a run, and [`socialcrawl_creators_manage`](/agent-tools/socialcrawl_creators_manage.json) saves and follows creators. The rules the tools carry are in [How should an agent call creator search?](/docs/prism/creators.md#how-should-an-agent-call-creator-search). ## Next steps - [Creator search](/docs/prism/creators.md): Every field, the markets table, what comes back and what each step costs. - [Credits](/docs/credits.md): How credits are billed, refunded and capped per key. - [Errors](/docs/errors.md): Every error type, what it means, and whether to retry.