Creator search quickstart: your first creators in five minutes

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.

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.

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"

{
  "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.

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"

{
  "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.

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"))

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.

Three requests are sent as POST /v1/prism/creators with a JSON body. All three are in Creator search:

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

Using an AI agent?

Give your agent the three creator tools, fetched as JSON with no key: socialcrawl_find_creators starts a search, socialcrawl_creators_run waits on, reads and resumes a run, and socialcrawl_creators_manage saves and follows creators. The rules the tools carry are in How should an agent call creator search?.

Next steps