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 or GitHub. For complete apps and runnable workflows, see the cookbook.

​

Install the SDK

npm

npm install influship

yarn

yarn add influship

pnpm

pnpm add influship

bun

bun add influship

​

Configure a server-side client

Set INFLUSHIP_API_KEY in your server environment:

export INFLUSHIP_API_KEY="your_api_key_here"

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 to use a returned creator ID in a second request, or run the 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 before adding retries around SDK calls.

For TikTok video search, a 200 response with data.videos: [], data.has_more: false, and data.next_cursor: null is successful completion. Stop your pagination loop without retrying that page. Continue while data.has_more is true, even on an empty page, using the returned cursor and the same query. See TikTok live data for pagination details.

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 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. The post response includes share_count and save_count when the source supplies them. An omitted view_count, share_count, or save_count means the count is unavailable. Preserve previously known counts and store zero when the response explicitly supplies it. media_count: null means the profile total is unknown. posts.length describes this response, and post_limit is an upper bound on the available recent posts.

Missing Instagram reel views receive one bounded native retry within the existing request budget. A successful post response is retained if views remain unavailable. engagement_rate: null means no measurable post sample is available; it is distinct from an observed zero rate.

TikTok counters also use null for unavailable observations. Photo-post links use /photo/, and slideshow images remain in source order. YouTube channel responses include available Shorts for Shorts-only channels and observed channel totals; search includes Shorts shelves. Keep YouTube search cursors unchanged, with the same query and filters. A cursor can retain the rest of a source page, so its scraped_at can match the preceding page.

For TikTok video search, pass data.next_cursor unchanged with the original query. Save the latest cursor after processing its page so you can resume with the same query. A page can contain fewer videos when some entries lack an author username. A successful response with data.has_more: false ends pagination, including when the final page is empty. See TikTok video search.

For YouTube search pagination, only a successful response with next_cursor: null marks completion. On temporary pagination 503 responses, preserve the cursor and collected results, then apply bounded backoff; restarting immediately does not guarantee availability. An invalid or oversized result page can return 502 upstream_contract_broken; stop automatic retries and retain collected results instead of treating that failure as an empty final page. Configure maxRetries: 0 when applying this policy with the SDK. See YouTube pagination.

For YouTube captions, stop automatic retries on 403 with error.details.upstream_error: content_unavailable; that response does not confirm video deletion. A 503 with content_not_ready identifies a scheduled video whose captions are not ready. Honor Retry-After: 300 and cap later attempts. Use maxRetries: 0 when applying this policy yourself. See caption availability.

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.

​

Call REST from Python

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

python -m pip install requests

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
Evaluate known Instagram handles	Score campaign fit
Resolve profiles and read timestamps	Understanding creator data
Fetch profiles, videos, or transcripts	Live platform data
Save a selection and review notes	Saved shortlists

Set up with a coding agent

Install the Influship SDK using this project's existing conventions.

CopiedCopy promptOpen in Cursor

The API Reference defines method signatures and response schemas. When upgrading, compare it with your installed SDK version.