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

# Build a Creator Shortlist

> Search ten creators, score campaign fit, and expand up to three candidates with a bounded runnable workflow

Build a reviewable shortlist by discovering candidates, scoring them against a campaign brief, and expanding up to three creator records. This recipe uses at most five API requests and 55.3 credits (\$0.553) when every stage reaches its limit.

For a browser app with CSV export, start with [Build a Creator Search App](/cookbook/creator-search-nextjs). This workflow adds campaign scoring and creator expansion.

## Run the complete program

[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+, pnpm 10.32.1, and an [API key](https://developers.influship.com).

```bash theme={null}
unzip cookbook-workflows.zip
cd workflows
pnpm install --frozen-lockfile
export INFLUSHIP_API_KEY="your_api_key_here"
pnpm shortlist "Fitness creators teaching approachable home workouts"
```

The [quickstart](/quickstart) covers key setup. Keep the key in your environment. The source uses the [TypeScript SDK](/sdks); `workflows.ts` contains the API stages and `cli.ts` handles command-line output and failures.

## The three stages

1. Search Instagram with `limit: 10` and your brief.
2. Match the distinct returned creator IDs against the same brief.
3. Expand up to three non-`avoid` results, ordered by campaign score, with `include: ['profiles']`.

An excerpt of the first call is:

```typescript theme={null}
const { data: search, response } = await client.search.create({
  query: brief,
  platforms: ['instagram'],
  limit: 10,
}).withResponse();
```

The full program validates a 3–500 character brief before making requests. An empty search stops before matching. Empty or entirely `avoid` match results stop before expansion. Duplicate creator IDs are scored only once. Expansion requests run sequentially, and automatic SDK retries are disabled.

`neutral` results remain available for manual review. Search relevance and campaign fit describe different questions; keep both rather than combining them into an unexplained score. See [Match Reasons](/concepts/match-reasons).

## Read the output

This abbreviated output uses **synthetic example data**:

```json theme={null}
{
  "searchId": "123e4567-e89b-12d3-a456-426614174000",
  "candidates": [{
    "search": {
      "creator": { "name": "Alex Example" },
      "primary_profile": null,
      "match": { "score": 0.4, "ranking_source": "retrieval_fallback", "low_confidence": true },
      "location_unverified": true
    },
    "campaign": {
      "decision": "neutral", "score": 0.8,
      "reasons": [{ "text": "Review the campaign alignment", "provenance": "inferred" }]
    },
    "creator": { "name": "Alex Example", "profiles": [] },
    "warning": null
  }],
  "usage": [{ "stage": "search", "credits": "27" }, { "stage": "campaign match", "credits": "1" }, { "stage": "creator expansion", "credits": "0.1" }],
  "creditsCharged": "28.10"
}
```

The full search record retains explanations, ranking source, confidence, and location verification. Campaign reasons retain structured provenance and supporting evidence. Creator-expansion warnings remain visible. Unknown metrics remain unknown. No score predicts sales or campaign ROI.

## Maximum intended cost

| Stage | Limit | Credits |
| - | - | -: |
| Search | 10 delivered creators | 45 |
| Campaign match | 10 distinct creators | 10 |
| Creator expansion | 3 records | 0.3 |
| **Maximum total** | **5 requests** | **55.3 (\$0.553)** |

Fewer results or expansions reduce the total. Actual usage comes from each response's `X-Credits-Charged` header; missing headers produce an unknown total. See [Pricing](/concepts/pricing).

## Verification and recovery

```bash theme={null}
pnpm type-check
pnpm test
```

The tests use the published SDK with synthetic HTTP responses. They verify stage boundaries and failure behavior without calling the API. Run a budgeted live command with your own key and review its returned creators separately.

A failure ends the program. The CLI reports the status, request ID and `Retry-After` when supplied; it does not silently repeat a billable stage. Follow [Error Handling](/guides/error-handling) before running it again. Re-running the command starts a new search.

## Save the reviewed selection

Select one to eight distinct Instagram profiles and follow [Save a Shortlist](/guides/saved-shortlists) to keep their usernames, your brief, and review notes. Saved lists cost no credits and are shared by API keys under the same account. Use the [creator research app](/cookbook/creator-research-app) for a complete selection and save interface.

## Related recipes

* [Compare Creators](/cookbook/compare-creators) scores handles directly when you already have candidates.
* [Expand with Lookalikes](/concepts/lookalikes) starts from an existing roster.
* [Export a Shortlist to CSV](/cookbook/export-shortlist-csv) exports a single search without expansion.
* [Browse the cookbook](/cookbook) for other workflows. [Contact support](mailto:elliot@influship.com) with the endpoint, status, and request ID; keep keys out of your report.


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