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

# Quickstart

> Make your first creator search, then retrieve a returned creator.

Create an API key in the [developer dashboard](https://developers.influship.com), then run these commands in a terminal with `curl`. The search requests five creators and costs up to **\$0.35**.

## Set your key

```bash theme={null}
export INFLUSHIP_API_KEY="your_api_key_here"
```

Keep the key server-side and out of version control.

## Search for five creators

```bash theme={null}
curl --fail-with-body --silent --show-error \
  'https://api.influship.com/v1/search' \
  -H "X-API-Key: $INFLUSHIP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"query":"fitness creators focused on practical home workouts","limit":5}'
```

The response contains `data`: a list of creators, their Instagram profiles, and match reasons. Read `data[].creator.id` to retrieve a creator, or `data[].match.reasons` to explain a result in your interface. A search can return fewer than five creators, including none.

<Accordion title="See an abbreviated, fictional search response">
  ```json theme={null}
  {
    "data": [{
      "creator": { "id": "123e4567-e89b-12d3-a456-426614174000", "name": "Alex Rivera" },
      "match": {
        "score": 0.91,
        "ranking_source": "reranked",
        "reasons": ["Publishes practical home-workout tutorials."]
      }
    }],
    "search_id": "987fcdeb-51a2-43d7-8b90-123456789abc",
    "total": 1,
    "quality": { "mode": "reranked", "reason": null },
    "has_more": false,
    "next_cursor": null
  }
  ```

  This illustrates fields, rather than output from a real account. The [Search reference](/api-reference/search/ai-powered-creator-search) contains the full schema.
</Accordion>

`quality.mode` and `match.ranking_source` distinguish AI-reranked results from retrieval fallback. A score is a ranking signal, not a percentage guarantee. See [search quality](/concepts/semantic-search#search-quality).

The POST already returns its visible results. [Saved search reads](/guides/pagination) reread them for free; they do not discover additional creators.

## Search and retrieve a creator

For the complete workflow, use Node.js 22+ with TypeScript or `curl` and `jq`. Each example retrieves a creator using an ID from your search response.

<Accordion title="Run the complete TypeScript or cURL example">
  <Tabs>
    <Tab title="TypeScript">
      Install the SDK and a TypeScript runner in your project:

      ```bash theme={null}
      pnpm add influship
      pnpm add -D tsx
      ```

      Save this as `quickstart.ts`:

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

      async function main() {
        if (!process.env.INFLUSHIP_API_KEY) {
          throw new Error('Set INFLUSHIP_API_KEY before running this script.');
        }
        const client = new Influship({ maxRetries: 0 });
        const search = await client.search.create({
          query: 'fitness creators focused on practical home workouts',
          limit: 5,
        });
        console.log(`Returned ${search.data.length} creators`);
        console.log(`Search quality: ${search.quality?.mode ?? 'reranked'}`);
        for (const result of search.data) {
          console.log(result.creator.name, result.match.ranking_source ?? 'reranked');
          console.log(result.match.reasons);
        }

        const first = search.data[0];
        if (!first) {
          console.log('No matches. Refine the query before making another search.');
          return;
        }
        const creator = await client.creators.retrieve(first.creator.id, {
          include: ['profiles'],
        });
        console.log(creator.data.name);
        for (const profile of creator.data.profiles ?? []) {
          console.log(`@${profile.username}: ${profile.followers ?? 'unknown'} followers`);
        }
      }

      main().catch((error) => {
        console.error(error.message);
        process.exitCode = 1;
      });
      ```

      Run it:

      ```bash theme={null}
      pnpm exec tsx quickstart.ts
      ```

      Use your project's package manager if it differs. [SDK setup](/sdks) includes npm, Yarn, and Bun commands.
    </Tab>

    <Tab title="cURL">
      Save this as `quickstart.sh`. It requires `jq` to carry a returned ID into the lookup:

      ```bash quickstart.sh theme={null}
      #!/usr/bin/env bash
      set -euo pipefail
      : "${INFLUSHIP_API_KEY:?Set INFLUSHIP_API_KEY before running this script}"
      command -v jq >/dev/null || { echo 'Install jq before running this script.' >&2; exit 1; }

      search=$(curl --fail-with-body --silent --show-error \
        'https://api.influship.com/v1/search' \
        -H "X-API-Key: $INFLUSHIP_API_KEY" \
        -H 'Content-Type: application/json' \
        -d '{"query":"fitness creators focused on practical home workouts","limit":5}')
      printf '%s\n' "$search" | jq '.data[] | {creator: .creator.name, reasons: .match.reasons}'
      creator_id=$(printf '%s\n' "$search" | jq -r '.data[0].creator.id // empty')
      if [[ -z "$creator_id" ]]; then
        echo 'No matches. Refine the query before making another search.'
        exit 0
      fi

      curl --fail-with-body --silent --show-error \
        "https://api.influship.com/v1/creators/$creator_id?include=profiles" \
        -H "X-API-Key: $INFLUSHIP_API_KEY" | jq '.data'
      ```

      ```bash theme={null}
      bash quickstart.sh
      ```
    </Tab>
  </Tabs>
</Accordion>

## Costs and failures

New API customers receive **500 starter credits**, with no card required. Search costs 25 credits plus 2 per creator delivered. Fetching one creator costs 0.1 credits. With five search results, the complete example costs **35.1 credits (\$0.351)**. Fewer results reduce that cost; an empty search still incurs its 25-credit base fee.

`X-Credits-Charged` reports the cost of a successful request. `RateLimit-Remaining-*` reports request-speed budgets, not your starter-credit balance. See [Pricing](/concepts/pricing) for the difference.

| Result | Next step |
| - | - |
| Empty search | Refine the brief or relax filters; each new search is billed |
| Missing profile or unknown metrics | Preserve `null`; choose a follow-up with [data freshness](/concepts/creators-vs-profiles) |
| `401` | Check the API key and header |
| `402` | Check your balance or billing; stop automatic retries |
| `429`, `500`, or `503` | Apply [bounded retries](/guides/error-handling#bounded-retries) |
| `502` | Stop automatic retries; follow [Error Handling](/guides/error-handling) |

## Build your workflow

<CardGroup cols={2}>
  <Card title="Score known handles" icon="users" href="/cookbook/score-campaign-fit">
    Resolve an existing list and evaluate campaign fit.
  </Card>

  <Card title="Build and save a shortlist" icon="list" href="/cookbook/build-a-shortlist">
    Review candidates, expand profiles, and keep selected creators.
  </Card>

  <Card title="Fetch live platform data" icon="bolt" href="/guides/live-platform-data">
    Start from an Instagram, TikTok, or YouTube resource.
  </Card>

  <Card title="Build a creator research app" icon="code" href="/cookbook/creator-research-app">
    Search, review evidence, and save selections in a complete interface.
  </Card>

  <Card title="Choose an app or workflow" icon="laptop-code" href="/cookbook">
    Run the Next.js starter or a complete campaign research script.
  </Card>
</CardGroup>


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