> ## Documentation Index
> Fetch the complete documentation index at: https://docs.influship.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Find Similar Creators

> Expand a creator selection using weighted examples and filters.

Start with an Instagram creator you already like and find others with similar content and style. Each result includes a similarity score and shared traits to review.

## Run a lookalike search

Set `INSTAGRAM_USERNAME` to a known Instagram handle, then run this with the [TypeScript SDK](/sdks):

```typescript theme={null}
import Influship from 'influship';

const username = process.env.INSTAGRAM_USERNAME;
if (!username) throw new Error('Set INSTAGRAM_USERNAME to your seed creator.');
const client = new Influship({ maxRetries: 0 });
const similar = await client.creators.lookalike({
  seeds: [{ platform: 'instagram', username }],
  limit: 5,
});

for (const result of similar.data) {
  console.log(result.creator.id, result.creator.name, result.similarity.score);
  console.log(result.similarity.shared_traits);
}
```

This returns up to five creators. With API-key or OAuth billing, lookalikes cost **1.5 credits per returned creator (\$0.015)**, with no base fee. The example costs at most **\$0.075**.

## Read the result

An abbreviated, fictional result:

```json theme={null}
{
  "data": [{
    "creator": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "Lena Park"
    },
    "similarity": {
      "score": 0.89,
      "shared_traits": [
        "Both publish practical strength-training tutorials",
        "Similar step-by-step presentation style"
      ]
    }
  }],
  "has_more": false,
  "next_cursor": null
}
```

`similarity.score` ranges from 0 to 1. Review it alongside `shared_traits`. To evaluate the new creators against a specific brief, continue with [campaign scoring](/cookbook/score-campaign-fit). To retrieve linked accounts, use each returned creator ID with [creator lookup](/concepts/creators-vs-profiles).

## Choose and weight your seeds

A seed is a reference creator. Provide **1–10 seeds**, identified by creator ID or Instagram username. You can mix these formats:

```json theme={null}
{
  "seeds": [
    { "creator_id": "123e4567-e89b-12d3-a456-426614174000", "weight": 1 },
    { "platform": "instagram", "username": "another_creator", "weight": 0.5 }
  ],
  "limit": 5
}
```

Weights range from **0 to 1**, defaulting to **1**. Give more weight to the creators who best represent the content you want. If you use campaign performance to choose weights, compare the results against an equally weighted search before adopting that approach.

Unresolved usernames are skipped when other seeds resolve. If none resolve, or a resolved seed is unavailable for similarity matching, the request returns `404 seed_not_found`. Check the handle or choose another seed before submitting another request.

## Narrow the results

Add filters when your roster needs specific account sizes or engagement levels:

```json theme={null}
{
  "seeds": [{ "platform": "instagram", "username": "your_seed_creator" }],
  "filters": {
    "followers": { "min": 25000, "max": 500000 },
    "engagement_rate": { "min": 2 },
    "verified": true
  },
  "limit": 5
}
```

| Parameter | Values |
| - | - |
| `filters.followers.min` / `.max` | Follower-count range |
| `filters.engagement_rate.min` / `.max` | Percentage range; `2` means 2% |
| `filters.verified` | `true` selects verified accounts |
| `limit` | 1–100 results per page; default 25 |

## Load another page

When `has_more` is `true`, repeat the request with the same seeds and filters, adding the returned `next_cursor` as `cursor`. Treat the cursor as an opaque string. Stop when `has_more` is `false`.

Each delivered page is billed per returned creator. See [Pagination](/guides/pagination) for the request pattern and the [Lookalike reference](/api-reference/creators/find-similar-creators) for all fields.

## Run a complete roster workflow

Find up to five similar creators from one to three seed handles, then score them against a campaign brief. The complete program makes at most two requests and costs up to **12.5 credits (\$0.125)** with API-key billing.

[Download the MIT-licensed workflow source](https://github.com/Influship/influship-examples/releases/download/v1.0.0/cookbook-workflows.zip) or [browse it on GitHub](https://github.com/Influship/influship-examples/tree/main/workflows). Requires Node.js 22+ and pnpm 10.32.1.

```bash theme={null}
unzip cookbook-workflows.zip
cd workflows
pnpm install --frozen-lockfile
export INFLUSHIP_API_KEY="your_api_key_here"
pnpm lookalikes "Approachable home workout content for beginners" your_seed_handle
```

Replace the seed with a real Instagram handle. Add up to two more handles after it. The program validates and deduplicates handles, starts with equal seed weights, and scores distinct returned creator IDs. An empty lookalike response stops before scoring. It retains similarity, shared traits, and campaign decisions separately. Automatic retries are disabled.

Run `pnpm type-check` and `pnpm test` for synthetic checks. Review actual returned creators and charges separately with your own key. A failure stops the program; follow [Error Handling](/guides/error-handling) before submitting again. Browse the [cookbook](/cookbook) for other workflows.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.