# 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 the fields you will add next.

## 1. Get your API key

New accounts get 100 credits on signup and no card is needed. The search on this page costs about 40 credits.

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&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=200)."
  },
  "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`, which is 200 on a GET unless you send another value.

## 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&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}.
for line in get(answer["data"]["next"]["results_url"] + "?format=compact").splitlines():
    creator = json.loads(line)
    if "key" in creator:
        print(creator.get("score"), creator["platform"], "@" + str(creator.get("username")), creator.get("followers"))
```

**TypeScript**

```typescript title="TypeScript"
const KEY = process.env.SOCIALCRAWL_API_KEY!;
const BASE = "https://www.socialcrawl.dev";

async function get(url: string): Promise<string> {
  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}.
const lines = (await get(`${answer.data.next.results_url}?format=compact`)).split("\n");
for (const line of lines.filter(Boolean)) {
  const c = JSON.parse(line);
  if (c.key) console.log(c.score, c.platform, `@${c.username}`, c.followers);
}
```

`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.

If the run stops at its `max_credits` cap, its status is `paused` and `next_step` says how many credits finish it. `POST` the `data.next.resume_url` it gives you and nothing already bought is bought again.

## 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 or LinkedIn too | `platforms=tiktok,instagram,youtube,twitter,linkedin` |
| The whole ask in one sentence | `prompt=UK fitness coaches on TikTok with 20k to 200k followers`, then read `data.request.compiled` |
| 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.