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.

Open in Cursor

TypeScript / JavaScript

Installation

npm
yarn
pnpm
bun

npm install influship

yarn add influship

pnpm add influship

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. TikTok profile-video responses contain only videos whose author matches the requested username, ignoring case and a leading @. The API filters cross-account entries from mixed live-source pages. A non-empty page with no matching videos returns 502 upstream_contract_broken, so integrations never need to discard another creator’s content themselves. Profile-video requests may wait briefly during traffic bursts while live-source capacity becomes available. Keep client concurrency bounded and retain the SDK’s normal request timeout. If a request returns 503 service_unavailable, retry with bounded exponential backoff and jitter instead of immediately fanning out more parallel requests.

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. Every live and raw endpoint (Instagram, YouTube, and TikTok) uses this same 503 envelope whenever live data is temporarily unavailable, so one retry path covers them all and 503 responses are never charged. YouTube transcript requests may recover from a temporary execution failure within the original request deadline. Set a total deadline for your integration and keep client retries bounded; a retry does not guarantee the source will become available. 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. Cancellation also applies during profile recovery and post retrieval. Treat a cancelled or timed-out request as incomplete; do not use a recovered profile as a successful result after its request budget expires. For Instagram post lookups, handle 503 service_unavailable caused by temporary source throttling through that same bounded retry path. Keep a total deadline across attempts and preserve cached data when retries are exhausted; a temporary access failure does not establish that the post was deleted. Use that bounded retry path for live Instagram profile availability failures too. Recovery stays within the request budget; failed recovery returns 503 service_unavailable rather than an empty profile to store as an inactive creator. Preserve your last cached profile and keep the original request options when retrying.

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. When reporting a TikTok upstream_contract_broken response, include the endpoint and request ID. Diagnostic details stay server-side; integrations should handle the documented error code rather than parse internal failure descriptions. 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. When saving a recovered Instagram profile, update only fields the response actually supplies. Preserve previously known business-account metadata when those fields are absent, and keep an unknown lifetime media total separate from the returned post count. Store unavailable counts as unknown rather than zero; an observed zero is a real measurement. Incomplete profile responses remain retryable availability failures rather than evidence that the creator has no followers.

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'])

Validate TikTok URLs

Pass a complete TikTok video URL to video, comments, replies and caption methods. A malformed value such as 1 returns a 400 validation error; fix the input rather than retrying it.

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.

Getting Started

Concepts

Guides

Cookbook

Billing & Limits

Integrations

Updates

SDKs

SDKs

Install with AI

TypeScript / JavaScript

Installation

Client Setup

Common Operations

Search

Lookalike

Campaign Match

Profile Lookup

Batch Lookup

Creator Email Lookup

TikTok Video Transcript

Error Handling

Instagram profile response fields

Health and Readiness

Python

Validate TikTok URLs

API Reference

​SDKs

​Install with AI

​TypeScript / JavaScript

​Installation

​Client Setup

​Common Operations

​Search

​Lookalike

​Campaign Match

​Profile Lookup

​Batch Lookup

​Creator Email Lookup

​TikTok Video Transcript

​Error Handling

​Instagram profile response fields

​Health and Readiness

​Python

​Validate TikTok URLs

​API Reference

SDKs

Install with AI

TypeScript / JavaScript

Installation

Client Setup

Common Operations

Search

Lookalike

Campaign Match

Profile Lookup

Batch Lookup

Creator Email Lookup

TikTok Video Transcript

Error Handling

Instagram profile response fields

Health and Readiness

Python

Validate TikTok URLs

API Reference