# Influencer Search Tool API: Rank by Median Views (https://www.socialcrawl.dev/blog/influencer-search-api)

> An influencer search tool needs a measuring engine underneath. See the API call that finds creators by median views, quotes the cost free, and caps the spend.

An influencer search tool is a form on top, and underneath it needs three things: a way to find creators who post about a topic, a measurement of what their posts actually get, and a price you can see before anything runs. `GET /v1/prism/creators` does all three in one call. It finds the creators for your keywords, platforms, market and size band, measures each from its recent non-pinned posts, and returns them ranked with a one-line reason. Build the form yourself, or skip the form and read the rows.

<CTA variant="soft" />

## What does an influencer search tool need underneath?

Most influencer search tools hand you a list sorted by followers. That works for browsing and fails for deciding, because followers say how many people subscribed once and nothing about how many watch now. A search you can build a campaign on needs the measured numbers behind each creator.

The creator search endpoint returns those numbers on every row: `median_views` (the typical post, with the pinned post left out), `engagement_rate`, `posts_per_week`, and `median_shares` and `median_saves` where the platform publishes them. It also returns `fit`, a judge's probability that the creator posts about your topic, and a `why` block that shows which filters each creator passed. It searches TikTok, Instagram and YouTube by default.

If you would rather use a finished product than build one, [influencer marketing platforms](/blog/influencer-marketing-platforms) compares them, and the [influencer discovery API](/solutions/influencer-discovery-api) page covers the same engine from the buyer's side.

## Why do follower counts mislead when you search for influencers?

Because one viral post moves an average and leaves the typical post where it was. A search for home espresso and pour over coffee creators on TikTok and Instagram, 10,000 to 250,000 followers, in the UK and US, returned eight creators. Four of them show the problem:

| Creator | Followers | Median views | Mean views |
| --- | --- | --- | --- |
| Creator B | 240,199 | 11,737 | 74,735 |
| Creator F | 29,815 | 19,288 | 20,890 |
| Creator D | 22,783 | 6,340 | 322,023 |
| Creator H | 91,723 | 11,147 | 449,172 |

Creator B has eight times the followers of Creator F and a typical post that gets 40% fewer views. Creator D's mean is about 50 times its median, because a single post carried the average. Sort by followers or by mean views and D and H look like stars. Sort by median views and Creator F leads.

That is why `median_views` is the field to filter on, and why the pinned post is excluded from it. A creator chooses what to pin, so a pinned post says nothing about a typical one and would skew the median. Every row reports `pinned_excluded`, the number of pinned posts it left out, and `signals.pinned_share`. In this search five of the eight rows had at least one pinned post removed. The row does not carry a with-pinned median, so the endpoint gives you the clean number and the count rather than both medians.

## How do you run an influencer search with one API call?

Send the keywords, the platforms and the size band, and add `dry_run=true` the first time. A dry run is free and starts nothing.

```bash
curl "https://www.socialcrawl.dev/v1/prism/creators?keywords=home+espresso,pour+over+coffee&platforms=tiktok,instagram&min_followers=10000&max_followers=250000&min_median_views=5000&country=GB,US&limit=8&max_credits=250&dry_run=true" \
  -H "x-api-key: $SOCIALCRAWL_API_KEY"
```

`min_median_views=5000` keeps only creators whose typical post reaches 5,000 views, so one lucky video cannot carry a small account over the line. `country=GB,US` keeps a creator only when its country is known and matches. The compiled request and the plan of searches come back with the quote, so you can check what the tool will do before it spends anything. Drop the `dry_run` parameter when the quote looks right.

<CTA variant="inline" />

## How do you price an influencer search before it runs?

Read the `estimate` block of the dry run. It gives `{ min, expected, max }` for the whole search and for one delivered creator, and tells you how many creators the cap is expected to buy:

```json
{
  "data": {
    "estimate": {
      "total": { "min": 29, "expected": 250, "max": 250 },
      "per_delivered": { "min": 3.63, "expected": 72.38, "max": 72.38 },
      "delivered": { "expected": 3, "max": 3 },
      "min_max_credits": 130,
      "answers_in_call": false
    },
    "next_step": "Send the same request without dry_run to start it; it runs in the background and answers 202 with the run ..."
  },
  "credits_used": 0
}
```

The expected total sits at 250 because that is the `max_credits` the request sent, and the run never spends past it. `answers_in_call: false` means the real call answers `202` and continues in the background. The answer also carries `suggested_max_credits`, the cap that leaves room to reach `limit`.

Treat the quote as a planning ceiling. For this request it expected three creators for the cap, and the real search delivered all eight for 122 credits. Your own dry run will differ with your niche and filters, so quote from your own request.

`min_max_credits` is the least cap the real call accepts. Send a lower `max_credits` and the call is refused before it starts, and the refusal is free:

```json
{
  "error": {
    "code": "INVALID_REQUEST",
    "details": {
      "reason": "max_credits_below_estimate",
      "min_max_credits": 130,
      "suggested_max_credits": 163
    }
  }
}
```

Show that `suggested_max_credits` to whoever approves the spend, then send the same request with it. The [credit pricing table](/docs/prism/creators) lists what each stage costs.

## What does a result row tell you?

Each row is one creator, measured. Here is the first creator from the search, trimmed to the fields you would screen on, with a placeholder handle:

```json
{
  "account": {
    "key": "tiktok:creator_a",
    "platform": "tiktok",
    "followers": 35417,
    "country": { "value": "US", "source": "author_declared" },
    "metrics": {
      "median_views": 8068,
      "mean_views": 22896,
      "engagement_rate": 0.119,
      "basis": "views",
      "posts_per_week": 8.44,
      "median_shares": 25,
      "median_saves": 73,
      "pinned_excluded": 3
    },
    "signals": { "pinned_share": 0.25 }
  },
  "judgments": { "fit": { "p": 0.93 } },
  "score": { "value": 0.86 },
  "why": {
    "matched_filters": [
      { "field": "min_followers", "value": 10000, "measured": 35417 },
      { "field": "min_median_views", "value": 5000, "measured": 8068 }
    ],
    "judgment_basis": "evidence and 12 walked captions"
  },
  "state": "kept"
}
```

`engagement_rate` is sums over sums on the platform's own basis, and `basis` says which: views on TikTok. `score` combines fit, engagement, posting activity and reach, and rows come back best first.

Screen on `why`. `matched_filters` pairs each filter you set with what was measured, so you can audit every pick: this creator was asked for a median of 5,000 views and measured 8,068. `judgment_basis` says what the fit judgment read. `fit` is a probability from a judge, and the weakest rows in the search sat at 0.50 and 0.59. Read `why` and `fit` before you put a creator into outreach.

## Which filters narrow an influencer search?

Beyond the size band and `min_median_views`, these are the filters people reach for:

- `country` and `exclude_country` keep or remove markets by the creator's own country, declared or read from where its posts come from.
- `min_engagement_rate` takes a fraction, so `0.03` means 3%.
- `account_kind` keeps `individual_creator`, `brand_or_business`, `media_or_publisher` or `fan_or_repost_page` accounts, which removes brand and repost pages from a creator list.
- `has_contact=email` keeps creators who show a public email. Leave it off until you need it. The search returns no addresses, and the email step is covered in the [TikTok email finder](/blog/tiktok-email-finder) guide.

Every filter is priced by the same dry run, so adding one shows you what it does to the quote.

## How does a background run finish?

A search for more than a handful of creators answers `202` with `data.run.run_id`. Poll `data.next.status_url` until `data.run.status` is `completed`; each poll waits up to 25 seconds for news. The creators are in the run's `results.jsonl`, one JSON object per line, or in JSON pages through `page_url`. The [creator search quickstart](/docs/prism/creators-quickstart) has a complete polling loop in Python and TypeScript.

A run does not always end with exactly `limit` creators. Three fields tell you what happened:

- `summary.short_reason` is `candidates_exhausted` when the searches ran out of candidates and `low_yield` when the last creators rarely passed your filters. It is `null` when the run met `limit`.
- `summary.more_available` says whether another pass can find more. When it is `true`, send the body in `data.next.more_url` to continue.
- `stopped_because: max_credits` means the run paused at your cap. `data.next.resume_url` carries the `suggested_max_credits` that finishes it.

## What other ways can you search for influencers?

Keywords are one mode of four, and each takes the same filters and the same dry run:

- `similar_to` takes one to five seed creators as `platform:handle` and finds lookalikes. Start there, then screen the rows. For the standalone TikTok lookalike endpoint, see [finding similar TikTok accounts](/blog/find-similar-tiktok-accounts).
- `handles`, or an `author_list_id` for a stored list, with a `purpose` ranks creators you already hold. Every handle comes back `kept` or `dropped` with its reason.
- `prompt` takes a sentence and compiles it into a search. Check `data.request.compiled` to see what it understood.
- `campaign` takes a description of a product and exists for briefs. Treat its output as a starting point as well.

If you are comparing this with a keyword search across every platform at once, [the social search engine post](/blog/social-search-engine) covers that call, and [social listening](/blog/social-listening-api) covers watching a topic over time instead of finding creators once. For the outreach step after this one, see [best influencer outreach APIs](/blog/best-influencer-outreach-api).

## What does influencer search not do?

It measures a creator's posts and says nothing about the person behind them. Limits to build around:

- It does not infer age, gender, ethnicity or other personal traits, and a request that asks for creators by those traits is refused.
- It never shows suppressed accounts.
- It returns no addresses.
- `limit` is a target. A run can end short, and `short_reason` says why.
- A creator whose country cannot be shown to match is dropped by default, so a country filter returns fewer rows and no guesses.
- `fit` is a judgment, and the first rows of any search are a shortlist to screen.

<CTA variant="hard" />

## Frequently asked questions

### What is an influencer search tool?

An influencer search tool finds creators who post about a topic and shows enough about each to choose between them. SocialCrawl's version is an API. `GET /v1/prism/creators` returns ranked creators with their median views, engagement rate and a reason for each pick, so you can build the interface yourself.

### Are there free influencer search tools?

Free web tools are a fine way to browse by hand. If you need ranked rows inside your own product, the API is the better fit. The dry run that quotes a search is free, and the search itself spends credits within the `max_credits` cap you set.

### How do you search for an influencer by niche and size?

Send `keywords` for the niche, `platforms`, and `min_followers` and `max_followers` for the size band. Add `min_median_views` to require a typical post that reaches a floor you choose. Run it with `dry_run=true` first to see the cost.

### What is an influencer discovery tool built on?

A discovery tool rests on three calls: a search for candidates, a lookup of each creator, and a walk of their recent posts to measure them. The creator search endpoint runs all three and bills each at its own public price, with no surcharge, so a dry run shows where the credits would go.

### Can an influencer search tool give me creator emails?

Creator search finds the creators, and the email step is separate. `has_contact=email` exists as a filter, and the [TikTok email finder](/blog/tiktok-email-finder) guide covers getting an address once you have a shortlist.

<FaqJsonLd
  faqs={[
    {
      question: "What is an influencer search tool?",
      answer:
        "An influencer search tool finds creators who post about a topic and shows enough about each to choose between them. SocialCrawl's version is an API. `GET /v1/prism/creators` returns ranked creators with their median views, engagement rate and a reason for each pick, so you can build the interface yourself.",
    },
    {
      question: "Are there free influencer search tools?",
      answer:
        "Free web tools are a fine way to browse by hand. If you need ranked rows inside your own product, the API is the better fit. The dry run that quotes a search is free, and the search itself spends credits within the `max_credits` cap you set.",
    },
    {
      question: "How do you search for an influencer by niche and size?",
      answer:
        "Send `keywords` for the niche, `platforms`, and `min_followers` and `max_followers` for the size band. Add `min_median_views` to require a typical post that reaches a floor you choose. Run it with `dry_run=true` first to see the cost.",
    },
    {
      question: "What is an influencer discovery tool built on?",
      answer:
        "A discovery tool rests on three calls: a search for candidates, a lookup of each creator, and a walk of their recent posts to measure them. The creator search endpoint runs all three and bills each at its own public price, with no surcharge, so a dry run shows where the credits would go.",
    },
    {
      question: "Can an influencer search tool give me creator emails?",
      answer:
        "Creator search finds the creators, and the email step is separate. `has_contact=email` exists as a filter, and the [TikTok email finder](/blog/tiktok-email-finder) guide covers getting an address once you have a shortlist.",
    },
  ]}
/>

<RelatedPosts currentSlug="influencer-search-api" tags={["product","development"]} locale="en" />