Skip to main content

​
Quickstart

By the end of this page, you’ll have searched for creators, fetched a full profile, and checked your usage. Three requests, and you’ll understand how the core API works.

​
Install and configure

Install the SDK and set your API key as an environment variable. 
npm install influship

export INFLUSHIP_API_KEY="your_api_key_here"
If you prefer raw HTTP, skip the install — you only need the API key in the X-API-Key header. For details on key management, scopes, and rotation, see the Authentication guide.
Never commit API keys to version control. Use environment variables or a secrets manager.

​
Search for creators

Search is the primary discovery endpoint. You pass a natural-language query describing the kind of creator you need, and the API returns ranked matches with scores and explanations. The query field accepts up to 500 characters of free text. The limit sets the maximum number of results for that . 
import Influship from 'influship';

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

const response = await client.creators.search({
  query: 'fitness creators focused on home workouts, consistent posting schedule',
  limit: 5,
  platforms: ['instagram', 'tiktok'],
  filters: {
    followers: { min: 50000 },
    engagement_rate: { min: 2.0 },
  },
});

console.log(response);
Filters are optional but useful for narrowing results. Available filter fields:
FilterTypeDescription
followers.min / followers.maxintegerFollower count range
engagement_rate.min / engagement_rate.maxnumberEngagement rate as percentage (2.0 = 2%)
verifiedbooleanOnly verified accounts
platforms (top-level)string[]Platforms to search, defaults to ["instagram"]

​
Inspect the response

Here’s an abbreviated version of what comes back: 
{
  "data": [
    {
      "creator": {
        "id": "a3f1b9c2-7d4e-4a8f-b6e1-2c9d5f8a0b3e",
        "name": "Alex Rivera"
      },
      "primary_profile": {
        "platform": "instagram",
        "username": "alexrivera.fit"
      },
      "match": {
        "score": 0.91,
        "reasons": [
          "Consistent home workout content with strong audience engagement"
        ]
      }
    },
    {
      "creator": {
        "id": "d7e4c1a8-3b2f-49d6-8e5c-1a7f3b9d2e6c",
        "name": "Maya Chen"
      },
      "primary_profile": {
        "platform": "tiktok",
        "username": "mayachen_fitness"
      },
      "match": {
        "score": 0.87,
        "reasons": [
          "Home fitness tutorials with high save rate and comment engagement"
        ]
      }
    }
  ],
  "search_id": "search_8f3a1b2c",
  "total": 2,
  "has_more": false,
  "next_cursor": null
}
A few fields worth noting:
  • creator — the canonical creator record. The id is what you use to fetch full profiles and pass to other endpoints.
  • primary_profile — the creator’s strongest social account for this query. A creator may have profiles on multiple platforms, but search surfaces the most relevant one.
  • match.score — a 0-to-1 relevance score. Higher means a closer fit to your query. Scores above 0.8 are typically strong matches.
  • match.reasons — human-readable explanations of why the creator matched. Useful for displaying to end users or for your own review.
Search accepts natural language. If your end users aren’t marketers, consider preprocessing their input with an LLM to improve result quality. Test both approaches — sometimes raw user input works fine, sometimes a refinement step makes a real difference.
The API Reference is the source of truth for exact response shapes, required fields, and edge cases. The examples on this page are abbreviated for clarity.

​
Fetch a creator by ID

Use the id from a search result to pull the full creator record. Add ?include=profiles to expand linked social profiles in the same response, so you don’t need a separate call for each platform. 
const creator = await client.creators.retrieve(
  'a3f1b9c2-7d4e-4a8f-b6e1-2c9d5f8a0b3e',
  { include: ['profiles'] }
);

console.log(creator);
The response includes the creator’s metadata along with an array of their social profiles — follower counts, engagement rates, content categories, and audience demographics for each platform.

​
Check cost and remaining budget

Every response includes billing and rate-limit headers. After the search request above, you’d see something like: 
X-Credits-Charged: 35.00
X-Credits-Features: creators.search
X-Billing-Plan: free
RateLimit-Remaining-Minute: 115
RateLimit-Remaining-Hour: 1465
Search billing breaks down like this:
ComponentCost
Base fee per search25
Per creator delivered2 credits
The base fee covers the AI inference that runs on every query. The per-creator fee scales with how many results you actually receive. With limit: 5 and five results returned, that’s 25 + (5 x 2) = 35 credits, or $0.35. If the API only finds 3 matches, you’d pay 25 + (3 x 2) = 31 credits — you’re never charged for results that don’t exist. The RateLimit-Remaining-* headers tell you how many requests you have left in the current window. Monitor these if you’re running batch searches. See Pricing for full cost rules and Rate Limits & Tiers for current budgets by plan.

​
Next steps

Creators vs. Profiles

Understand the data model and when to use each resource

How Search Works

Query syntax, scoring, and how to get the best results

SDK Guide

Typed client setup, error handling, and pagination

API Reference

Full endpoint specs with generated examples for every route