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

# Score Campaign Fit for an Existing List

> Resolve up to ten Instagram handles, retain profile data, and score distinct creators against a campaign brief

Resolve Instagram handles into profile records, then score their distinct creators against a campaign brief. Use this workflow when you need profile data as well as campaign scores. [Compare Creators](/cookbook/compare-creators) accepts handles directly and skips the separate lookup when you only need scores.

## 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 score-list "Practical healthy meals for busy professionals" first_real_handle second_real_handle
```

Replace the handles with your candidates. The program accepts up to ten, ignoring duplicate handles and a leading `@`. The [quickstart](/quickstart) covers key setup. Keep keys in the environment. See the [TypeScript SDK](/sdks) for client details.

## Resolution and scoring

The first request resolves your supplied handles:

```typescript theme={null}
const { data: lookup, response } = await client.profiles.lookup({
  profiles: handles.map((username) => ({ platform: 'instagram', username })),
}).withResponse();
```

The complete program is in `workflows.ts`. It keeps lookup records in the output, deduplicates non-null creator IDs, then sends one campaign-match request. If no handles resolve, it stops before matching. It does not invent scores for unresolved creators. Automatic retries are disabled.

Campaign results are sorted by fit score, with `good`, `neutral`, and `avoid` decisions available for manual review. Structured reasons retain their provenance and supporting evidence. See [Match Reasons](/concepts/match-reasons); a score describes this brief, not a creator's overall quality or likely campaign ROI.

## Read the output

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

```json theme={null}
{
  "profiles": [{ "username": "alex_example", "creator_id": "123e4567-e89b-12d3-a456-426614174000", "follower_count": null }],
  "candidates": [{
    "creator": { "id": "123e4567-e89b-12d3-a456-426614174000", "name": "Alex Example" },
    "match": { "decision": "neutral", "score": 0.63, "reasons": [{ "text": "Review the food content", "provenance": "inferred" }] }
  }],
  "usage": [{ "stage": "profile lookup", "credits": "0.1" }, { "stage": "campaign match", "credits": "1" }],
  "creditsCharged": "1.10"
}
```

Keep unknown metrics as unknown. Inspect which handles resolved using the profile records rather than assuming one result per input.

## Maximum intended cost

| Stage | Limit | Credits |
| - | - | -: |
| Profile lookup | 10 resolved profiles | 1 |
| Campaign match | 10 distinct creators | 10 |
| **Maximum total** | **2 requests** | **11 (\$0.11)** |

The program reads actual charges from `X-Credits-Charged` on each response. Missing headers produce an unknown total. Fewer resolved profiles and deduplicated creators reduce usage. See [Pricing](/concepts/pricing).

## Verification and recovery

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

Tests use the published SDK with synthetic HTTP responses and make no live calls. Verify access, returned profiles, campaign reasons, and actual charges separately with a budgeted real request.

A failure ends the program; the CLI reports status, request ID and `Retry-After` when supplied. Follow [Error Handling](/guides/error-handling) before running it again. The command does not automatically retry or hide a failed lookup as a successful empty list.

## Related resources

* [Compare Creators](/cookbook/compare-creators) skips profile resolution when you only need campaign scores.
* [Creator Search App](/cookbook/creator-search-nextjs) discovers new candidates with a browser UI.
* [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.