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

# Client Setup

> Install the TypeScript SDK or call REST from another language.

Use the `influship` package for typed JavaScript and TypeScript requests. For other languages, call the REST API with your HTTP client.

Browse the SDK on [npm](https://www.npmjs.com/package/influship) or [GitHub](https://github.com/Influship/influship-sdk-typescript). For complete apps and runnable workflows, see the [cookbook](/cookbook).

## Install the SDK

<Tabs>
  <Tab title="npm">
    ```bash theme={null}
    npm install influship
    ```
  </Tab>

  <Tab title="yarn">
    ```bash theme={null}
    yarn add influship
    ```
  </Tab>

  <Tab title="pnpm">
    ```bash theme={null}
    pnpm add influship
    ```
  </Tab>

  <Tab title="bun">
    ```bash theme={null}
    bun add influship
    ```
  </Tab>
</Tabs>

## Configure a server-side client

Set `INFLUSHIP_API_KEY` in your server environment:

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

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

const client = new Influship({ maxRetries: 0 });
const search = await client.search.create({
  query: 'sustainable fashion creators who explain clothing repair',
  limit: 5,
});

for (const result of search.data) {
  console.log(result.creator.name, result.match.reasons);
}
```

The client reads `INFLUSHIP_API_KEY` automatically. You can also pass `apiKey` explicitly. Keep the client in a server action, route handler, backend service, or CLI; keep the key out of browser bundles and version control.

Each result contains `creator`, profile summaries, and `match`. Follow the [Quickstart](/quickstart) to use a returned creator ID in a second request, or run the [creator research app](/cookbook/creator-research-app).

## Handle typed errors

For transcript requests, keep request failures separate from successful empty transcript results. A failed media download does not establish that a video contains no speech. A language hint controls transcription; it is not a request to translate cached text.

Treat `post` in an Instagram transcript response as optional. When a completed transcript is reused, the response omits post metadata. Fetch `GET /v1/raw/instagram/post/{shortcode}` separately when you need current post stats or media URLs. Keep the same language setting when repeating a transcript request.

The SDK retries some failures twice by default. The example sets `maxRetries: 0` so your application controls retry behavior.

For live TikTok `503` responses, honor `Retry-After` when present and keep retry attempts bounded. Retrying a settled x402 or MPP request requires another payment. See the [TikTok retry rules](/guides/tiktok-live-data#url-and-retry-rules) before adding retries around SDK calls.

```typescript theme={null}
import { APIError, RateLimitError } from 'influship';

try {
  await client.search.create({ query: 'clothing repair tutorials', limit: 5 });
} catch (error) {
  if (error instanceof RateLimitError) {
    console.error('Rate limited. Retry-After:', error.headers?.get('retry-after'));
  } else if (error instanceof APIError) {
    console.error(error.status, error.code, error.message);
  } else {
    throw error;
  }
}
```

For `429`, `500`, and temporary `503` responses, use bounded retries with a total deadline and honor `Retry-After`. For `402`, check billing before sending another request. For `502 upstream_contract_broken`, stop automatic retries; a source query or validation failure does not confirm account deletion. Use available cached data and contact support if the issue persists. The [Error Handling guide](/guides/error-handling) includes the complete policy and a retry example.

For live Instagram requests, budget for the complete response, including recovery. Recovery uses the request's remaining execution time; it does not start a fresh timeout window. Keep subsequent API retries within your total deadline.

Live Instagram posts include available photos, carousels, and videos. Treat an omitted `view_count` as unavailable, and `media_count: null` as an unknown profile total. Preserve previously known metrics instead of replacing unavailable values with zero. `posts.length` describes this response, and `post_limit` is an upper bound on the available recent posts.

Choose your media renderer using `post_type`. Images and videos do not require `carousel_items`; image posts and image carousel children do not require `video_url`. Validate the fields needed for each media type instead of requiring every optional media field on every post.

Missing bio links or pronouns do not make a profile unavailable. Preserve unknown optional metrics, and check `engagement_visibility.like_and_view_counts_disabled` before treating a zero like count as observed engagement. A response with incomplete required identity, engagement, or media fields returns an acquisition error rather than invented values or a silently shortened selected post list.

Optional post captions, tags, location, music, and display variants are omitted or returned as null when unavailable. Treat absent metadata as unknown: an omitted tag list or paid-partnership flag does not establish that the post has no tags or paid partnership. Use the validated primary media fields to display the post, and check optional fields before using them.

Instagram request success and media download success are separate outcomes. Source URLs can expire; repeat the post lookup to obtain a fresh URL before a bounded download retry. An unavailable public post is not proof of deletion.

When requesting a profile with recent posts, allow time to retrieve the complete response within your configured deadline. Wait for that request to finish before issuing a bounded retry.

Unavailable or gated Instagram media returns a temporary failure; it does not establish deletion. A selected post with unavailable media prevents a complete profile response. Keep retries bounded, and preserve the previously saved profile and posts when acquisition fails.

When merging live Instagram profile responses, treat `bio_links` as available valid links. Recovery excludes unusable source entries; an empty array or `external_url: null` does not establish that a creator removed their website. Preserve previously known website data when the new response provides no usable link. See [Instagram profile metadata](/guides/download-instagram-videos#profile-counts-and-omitted-fields).

## Call REST from Python

Install `requests`, then read the same server-side environment variable:

```bash theme={null}
python -m pip install requests
```

```python theme={null}
import os
import requests

response = requests.post(
    'https://api.influship.com/v1/search',
    headers={'X-API-Key': os.environ['INFLUSHIP_API_KEY']},
    json={'query': 'creators who teach clothing repair', 'limit': 5},
    timeout=60,
)
response.raise_for_status()
for result in response.json()['data']:
    print(result['creator']['name'], result['match']['reasons'])
```

## Continue with your workflow

| Task | Guide |
| - | - |
| Find more creators like a reference account | [Find similar creators](/concepts/lookalikes) |
| Evaluate known Instagram handles | [Score campaign fit](/cookbook/score-campaign-fit) |
| Resolve profiles and read timestamps | [Understanding creator data](/concepts/creators-vs-profiles) |
| Fetch profiles, videos, or transcripts | [Live platform data](/guides/live-platform-data) |
| Save a selection and review notes | [Saved shortlists](/guides/saved-shortlists) |

<Accordion title="Set up with a coding agent">
  <Prompt description="Install the Influship SDK using this project's existing conventions." actions={["copy", "cursor"]}>
    Add the Influship API to this project.

    First inspect the repository to identify its language, framework, package manager, environment-variable conventions, and existing API client patterns. Preserve those conventions.

    For a TypeScript or JavaScript project:

    1. Install the official `influship` package with the repository's existing package manager.
    2. Configure a server-side Influship client that reads `INFLUSHIP_API_KEY` from the environment.
    3. Add `INFLUSHIP_API_KEY=` to the appropriate example environment file. Never put a real key in source code, generated files, logs, client-side bundles, or version control.
    4. Add a small, reusable example for natural-language creator search using `client.search.create({ query, limit: 5 })`. Keep it behind an existing server-side boundary such as a server action, route handler, backend service, or CLI command.
    5. Set `maxRetries: 0`, then use the SDK's exported error classes to apply bounded retries for 429 and temporary 503 responses. Honor `Retry-After`. Do not automatically retry 402 or `502 upstream_contract_broken`.

    For another language, use the REST API with base URL `https://api.influship.com` and an `X-API-Key` header and follow the project's existing HTTP-client conventions.

    Use [https://docs.influship.com/sdks](https://docs.influship.com/sdks) and [https://docs.influship.com/api-reference](https://docs.influship.com/api-reference) as the contract. Run the relevant local formatting, type-check, and test commands. Verify locally with mocked HTTP first. If `INFLUSHIP_API_KEY` is available, make one creator search with `limit: 1` to verify the integration. Finish by listing the files changed, where I should set `INFLUSHIP_API_KEY`, and the verification result.
  </Prompt>
</Accordion>

The [API Reference](/api-reference) defines method signatures and response schemas. When upgrading, compare it with your installed SDK version.


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