Quickstart

Search for creators, fetch a creator record, and understand billing in under five minutes

Quickstart

By the end of this page, you’ll have searched for creators, fetched a full creator record, and inspected the usage headers on both requests.

Install and configure

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

npm

npm install influship

pnpm add influship

yarn add 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 search session.

SDK

import Influship from 'influship';

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

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

console.log(response);

curl -X POST https://api.influship.com/v1/search \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "fitness creators focused on home workouts, consistent posting schedule",
    "limit": 5,
    "filters": {
      "followers": { "min": 50000 },
      "engagement_rate": { "min": 2.0 }
    },
    "platforms": ["instagram"]
  }'

Filters are optional but useful for narrowing results. Available filter fields:

Filter	Type	Description
followers.min / followers.max	integer	Follower count range
engagement_rate.min / engagement_rate.max	number	Engagement rate as percentage (2.0 = 2%)
verified	boolean	Only 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"
      },
      "relevant_profile": {
        "platform": "instagram",
        "username": "alexrivera.fit"
      },
      "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"
      },
      "relevant_profile": {
        "platform": "instagram",
        "username": "mayachen.fitness"
      },
      "primary_profile": {
        "platform": "instagram",
        "username": "mayachen.fitness"
      },
      "match": {
        "score": 0.87,
        "reasons": [
          "Home fitness tutorials with high save rate and comment engagement"
        ]
      }
    }
  ],
  "search_id": "8f3a1b2c-4d5e-4678-9abc-1234567890de",
  "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.
• relevant_profile — the profile most relevant to the query, or null when no profile data is available.
• primary_profile — the creator’s largest profile, or null when no profile data is available.
• 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.

SDK

const creator = await client.creators.retrieve(
  'a3f1b9c2-7d4e-4a8f-b6e1-2c9d5f8a0b3e',
  { include: ['profiles'] }
);

console.log(creator);

curl "https://api.influship.com/v1/creators/a3f1b9c2-7d4e-4a8f-b6e1-2c9d5f8a0b3e?include=profiles" \
  -H 'X-API-Key: YOUR_API_KEY'

The response includes the creator’s metadata and an array of linked profile summaries with usernames, follower counts, engagement rates, and verification status.

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:

Component	Cost
Base fee per search	25 credits
Per creator delivered	2 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 rate-limit credits remain 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