SDKs

Install the TypeScript SDK and start making API calls in minutes

SDKs

The TypeScript SDK is auto-generated from the OpenAPI spec. It gives you typed methods, request/response models, and automatic error classes — so you spend less time reading docs and more time building.

Install with AI

Copy this prompt into Codex, Claude Code, Cursor, or another coding agent.

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

CopiedCopy promptOpen in Cursor

TypeScript / JavaScript

Installation

npm

npm install influship

yarn

yarn add influship

pnpm

pnpm add influship

bun

bun add influship

Client Setup

import Influship from 'influship';

const client = new Influship({
  apiKey: process.env.INFLUSHIP_API_KEY,
});

If INFLUSHIP_API_KEY is set in your environment, you can skip the config object entirely:

const client = new Influship();

Common Operations

Search

Search accepts a natural language query and returns ranked creators. Describe the kind of creator you need — the API handles the matching.

const results = await client.search.create({
  query: 'sustainable fashion creators',
  limit: 10,
  filters: {
    followers: { min: 10000, max: 500000 },
    engagement_rate: { min: 2.0 },
  },
});

for (const result of results.data) {
  console.log(result.creator.name, result.match.score);
}

Start with a small limit (5-10) while prototyping. Larger limits cost more credits and usually return diminishing-value results past the top 15-20.

Lookalike

Find creators similar to ones you already know. You can weight seeds to influence which traits matter more in the results.

const similar = await client.creators.lookalike({
  seeds: [
    { platform: 'instagram', username: 'fitness_coach_jane', weight: 1.0 },
    { platform: 'instagram', username: 'wellness_daily', weight: 0.5 },
  ],
  limit: 15,
});

A higher weight means the API leans more heavily on that seed’s profile characteristics. Use this when one seed is a better example of what you want than the others.

Campaign Match

Score how well specific creators fit a campaign brief. Each result includes a decision (strong fit, moderate fit, or weak fit) and a numeric score.

const fit = await client.creators.match({
  creators: [
    { creator_id: '123e4567-e89b-12d3-a456-426614174000' },
    { creator_id: '987fcdeb-51a2-43d7-8b90-123456789abc' },
  ],
  intent: {
    query: 'Promote a new plant-based protein bar',
    context: 'Target audience is health-conscious millennials aged 22-35',
  },
});

for (const result of fit.data) {
  console.log(result.match.decision, result.match.score);
}

Profile Lookup

Retrieve a single creator profile by platform and username.

const profile = await client.profiles.get('jamietravels', { platform: 'instagram' });

Batch Lookup

Look up multiple profiles in a single request. This is more efficient than calling profiles.get in a loop — one request, one billing event.

const profiles = await client.profiles.lookup({
  profiles: [
    { platform: 'instagram', username: 'jamietravels' },
    { platform: 'instagram', username: 'chefmarco' },
  ],
});

Profile lookups are cheap but add up at scale. Cache these responses if your use case allows it — creator data doesn’t change often.

Creator Email Lookup

Fetch known email addresses for creators. Identify each creator by Influship creator_id or by platform + username — you can mix both in one request. Response rows preserve the input order.

const emails = await client.creatorEmails.lookup({
  creators: [
    { platform: 'instagram', username: 'jamietravels' },
    { creator_id: '123e4567-e89b-12d3-a456-426614174000' },
  ],
});

Emails can be unvalidated, so check each status before treating an address as deliverable. You’re charged only for resolved creators that return at least one email.

TikTok Video Transcript

Fetch a transcript from a TikTok video URL. The response contains plain text and timestamped segments with millisecond offsets.

Each successful transcript costs 2.5 credits ($0.025), including reused results. TikTok profile, video-detail, sound-detail and comment-page requests cost 0.2 credits ($0.002).

Sound details are available through GET /v1/raw/tiktok/music?music_id=.... Use the exact sound clip ID as a string. Unknown fields are null; audio and cover URLs are temporary links rather than durable downloads.

Pass video.music.music_id unchanged when it is non-null. Do not use Number() or parseInt() on TikTok IDs; large IDs exceed JavaScript’s safe integer range.

Caption-only responses are available through GET /v1/raw/tiktok/video/captions?url=... (OpenAPI operation getLiveTikTokVideoCaptions). This returns existing captions without generating a transcript and costs 0.2 credits per successful response. Missing captions return transcript_not_available.

const result = await client.raw.tiktok.getVideoTranscript({
  url: 'https://www.tiktok.com/@creator/video/7517114944362499342',
});

console.log(result.data.full_text);
for (const segment of result.data.segments) {
  console.log(segment.start_ms, segment.end_ms, segment.text);
}

The response reports the detected language. The generated client uses a 210-second request timeout so a transcript can complete within the API’s 180-second execution budget. See TikTok live data for profile, video, comment, media URL, and transcript behavior.

For TikTok profile-video and comment pagination, pass next_cursor unchanged with the same resource and query options. Cursors are opaque strings of up to 2,048 characters; do not parse them or convert them to numbers. If the API returns 400 validation_error for an invalid or expired cursor, restart without a cursor rather than retrying the same page token.

Error Handling

The SDK exports typed error classes so you can handle failures precisely.

import Influship, { APIError, RateLimitError } from 'influship';

try {
  const results = await client.search.create({ query: 'fitness' });
} catch (error) {
  if (error instanceof RateLimitError) {
    console.log('Account rate limited, retry after:', error.headers?.get('retry-after'));
  } else if (error instanceof APIError && error.status === 402) {
    console.log('Billing or subscription action required:', error.message);
  } else if (error instanceof APIError && error.status === 503) {
    console.log('Temporary upstream issue, retry after:', error.headers?.get('retry-after'));
  } else if (error instanceof APIError && error.status === 502) {
    console.log('Upstream data unusable — do not retry, use cached data');
  } else if (error instanceof APIError) {
    console.log('API error:', error.status, error.message);
  }
}

Most authenticated 402 responses use payment_required with a reason_code for the billing or subscription state and a next_step for the recovery action. Search can return insufficient_credits instead when remaining credits cannot cover the request. Branch on error.code. Do not retry automatically. Temporary failures while checking billing state use retryable 503 responses instead.

429 rate_limit_exceeded means your API key hit its account-level quota. Live-data requests can return 503 service_unavailable when they cannot be completed. Honor Retry-After when present, use bounded exponential backoff, and add jitter between attempts.

YouTube search retries one eligible connection failure within the request deadline. A 503 can also represent another temporary upstream failure. Apply the normal bounded backoff instead of immediately replaying the request in a tight loop.

Instagram profile requests attempt recovery from temporary source failures within the request budget. A successful recovery uses the same response schema; an unsuccessful recovery returns an error, not a partial successful profile. Keep retries bounded and honor Retry-After when present.

Instagram profile response fields

For raw Instagram profile responses, media_count is the total profile media count when available, or null when unknown. Zero means an observed total of zero. Use posts.length for the number of posts returned by this request; do not substitute it for the lifetime total or convert null to zero.

The raw profile response does not include highlight_reel_count, is_business, or is_professional. Remove reads of these fields from your integrations; their absence does not mean zero highlights or a non-business account. These changes apply to raw Instagram profiles, not cached profile lookups or TikTok responses. When upgrading SDKs, handle media_count as nullable.

Keep 502 upstream_contract_broken out of that retry path. It means the API could not process the source data. Do not retry automatically; use your last cached value and contact support if the issue persists. Retrying an already-settled x402 or MPP request requires another payment.

Health and Readiness

GET /health is the unauthenticated process-liveness check. It answers when the API process is running, even if a downstream dependency is temporarily unavailable.

GET /ready is the unauthenticated dependency-readiness check for operators and load balancers. It checks required downstream dependencies in parallel, returning 200 only when every dependency is ready and 503 otherwise. The response exposes status and latency per dependency without credentials or upstream error details.

See Error Handling for the full error reference.

Python

There is no official Python SDK. Use the REST API directly with requests or httpx.

import requests

response = requests.post(
    'https://api.influship.com/v1/search',
    headers={'X-API-Key': 'your_api_key'},
    json={
        'query': 'sustainable fashion creators',
        'limit': 10,
    },
)

data = response.json()
for result in data['data']:
    print(result['creator']['name'], result['match']['score'])

API Reference

The API Reference is generated from the same spec as the SDK. Use it for the most up-to-date method signatures and response shapes. If the SDK types and the reference ever seem to disagree, the reference reflects the latest deployed version.