API Reference

Comprehensive documentation for the Influship API. Build powerful influencer marketing applications with our AI-powered search, analysis, and matching capabilities.

Base URL

All API requests are made to:

https://api.influship.com

Authentication

All endpoints (except /health) require an API key passed in the X-API-Key header:

curl -H "X-API-Key: YOUR_API_KEY" https://api.influship.com/v1/search

Keep your API key secure! Never expose your API key in client-side code or public repositories. Treat it like a password.

Pagination

Endpoints returning lists use cursor-based pagination for efficient data traversal:

How It Works

Request with limit - Set how many results you want per page (default: 25, max: 100)
Check has_more - Response indicates if more results exist
Use next_cursor - Pass this value as cursor parameter for the next page
Track total - Use filtered_total to show total matching results

curl "https://api.influship.com/v1/search?limit=25" \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "fitness influencers"}'
  
# Response includes:
# {
#   "items": [...],
#   "filtered_total": 247,
#   "has_more": true,
#   "next_cursor": "eyJpZCI6MjV9"
# }

Cursors are opaque - They’re base64-encoded strings containing pagination state. Never try to construct or decode them manually. Always use the exact next_cursor value from the previous response.

Pagination Fields

limit

integer

default:"25"

Number of results per page. Min: 1, Max: 100

cursor

string

Opaque pagination cursor from previous response’s next_cursor

filtered_total

integer

Total matching results before pagination. Use this to show “25 of 1,247 results”

has_more

boolean

Whether additional pages exist. If true, use next_cursor to fetch more

Response Format

Success Response

All successful responses follow this structure:

{
  "items": [...],          // Or other data field
  "filtered_total": 247,   // Total matching results (for paginated endpoints)
  "has_more": true,        // More pages available
  "next_cursor": "..."     // Cursor for next page
}

Error Response

All errors include a structured error object with actionable details:

{
  "error": {
    "code": "validation_error",
    "message": "Request validation failed",
    "details": {
      "fields": ["query"],
      "context": "query must be between 1-500 characters"
    },
    "request_id": "req_8a7b9c0d1e2f3g4h"
  },
  "timestamp": "2024-01-15T10:30:00.000Z"
}

Common Error Codes

validation_error - Request validation failed (400)
unauthorized - Invalid or missing API key (401)
not_found - Resource not found (404)
rate_limit_exceeded - Too many requests (429)
internal_error - Server error (500)

Endpoint-Specific Errors

seed_not_found - Lookalike seed creator not found (404)
invalid_seeds - Invalid seed data provided (400)
brand_safety_failed - Brand safety analysis failed (500)
post_analysis_failed - Post analysis failed (500)

Response Headers

Every API response includes metadata headers for tracking usage and limits:

Billing & Usage Headers

X-Request-Id

string

Unique identifier for this request. Include in support tickets for faster troubleshooting.Example: req_8a7b9c0d1e2f3g4h

X-Credits-Charged

string

Exact number of credits consumed by this requestExample: 4.15

X-Credits-Features

string

Comma-separated list of features that impacted billingExample: detailed_mode,ai_analysis

X-Billing-Plan

string

Your current billing plan identifierExample: pro

Rate Limit Headers

RateLimit-Limit

string

Maximum requests allowed in the current time windowExample: 10000

RateLimit-Remaining

string

Requests remaining in current windowExample: 9995

RateLimit-Reset

string

Unix timestamp (seconds) when rate limit resetsExample: 1704124800

Credits & Billing

The Influship API uses a flexible credit-based system that scales with your usage.

Pricing Models

Search & Discovery

Creator Search: 2.0 credits per creatorLookalike: 1.0 credit per creatorDetailed mode: +0.05 per social accountExample: 10 creators in detailed mode with 3 profiles each = 20 + (10 × 3 × 0.05) = 21.5 credits

Creator Data

Creator Profiles: 0.1 credits per creatorProfile Lookup: 0.01-0.05 credits (lite/detailed)Autocomplete: 0.001 credits per request

Content Analysis

Post Analysis: 1.0 credit per postAI Analysis: +0.5 credits per postBrand Safety: +0.5 credits per postExample: 1 post with both features = 1.0 + 0.5 + 0.5 = 2.0 credits

Brand Safety & Matching

Creator Analysis: 2.0 credits per creatorProfile Analysis: 2.0 credits per profilePost Analysis: 0.5 credits per postCreator Matching: 0.1 credits per creator

See detailed pricing with real-world examples in our Pricing Guide.

Common Patterns

Understanding these workflows helps you build efficient integrations.

1. Discovery → Enrichment Flow

Lookup by Username

Call /v1/profiles with username + platformResult: Social account data + creator_profile_id

Get All Accounts

Use creator_profile_id with /v1/creators/{id}/profilesResult: All social accounts for that creator

Get Creator Info

Use creator_profile_id with /v1/creatorsResult: Person-level data (name, bio, avatar)

2. Search → Analysis Flow

Use /v1/search with natural language queryResult: Matching creators with AI recommendations

Analyze

Use returned creator IDs with brand safety or match endpointsResult: Suitability scores and risk assessment

Deep Dive

Get posts via /v1/posts/by-creator for content analysisResult: Detailed post data with optional AI features

3. Lookalike Discovery

Identify Seeds

Choose 1-10 seed creators (by ID or username+platform)Add optional weights (0-10) to prioritize certain seeds

Set Filters

Define audience size, engagement rate, platforms, verificationFilter results to match your campaign criteria

Get Results

API returns similar creators ranked by AI similarity scoreEach result includes explanation of why they’re similar

Platform Support

Instagram

string

default:"✅ Fully Supported"

All endpoints support Instagram with complete feature coverage

TikTok

string

default:"✅ Supported"

Available on most endpoints - check endpoint-specific documentation

YouTube, Twitter/X

string

default:"🔜 Coming Soon"

Additional platforms in development

Data Concepts

Creator vs Profile Data

Understanding the difference is key to using the API effectively:

Creator Data

Person-level information

Name, bio, avatar
Cross-platform identity
Aggregated information

Endpoint: /v1/creators

Profile Data

Platform-specific metrics

Follower counts, engagement
Verified status
Platform username & handle

Endpoints: /v1/profiles, /v1/creators/{id}/profiles

Response Modes

Control the level of detail in API responses:

mode

string

default:"lite"

lite - Basic fields only (faster, cheaper)detailed - Extended metrics and analytics (+0.05 credits per social account)

Lite Mode Fields

Basic profile info (username, display name, bio)
Follower count, engagement rate
Verification status
Avatar and external URLs

Detailed Mode Additional Fields

Average comments & video views
Monthly follower growth rate
Platform category
Following count, media count
Highlight reel count (Instagram)

Rate Limits

Rate limits ensure fair usage and system stability:

By Plan

Free: 1,000 requests/hour
Pro: 10,000 requests/hour
Enterprise: Custom limits (50,000+)

All responses include RateLimit-* headers. Monitor these to avoid hitting limits. See our Rate Limits Guide for handling strategies.

HTTP Status Codes

200

Success

Request successful, response contains requested data

400

Bad Request

Invalid request parameters or validation failed

401

Unauthorized

Missing or invalid API key

404

Not Found

Requested resource doesn’t exist

429

Rate Limited

Too many requests - check Retry-After header

500

Internal Error

Server error - contact support with X-Request-Id

API Endpoints

Search Creators

POST /v1/searchAI-powered influencer discovery with natural language queries

Autocomplete

GET /v1/creators/autocompleteReal-time search suggestions for creator discovery

Get Creators

GET /v1/creatorsRetrieve creator profiles by ID with optional social accounts

Get Profiles

POST /v1/profilesLook up social accounts by username and platform

Creator's Profiles

GET /v1/creators/{id}/profilesGet all social accounts for a specific creator

Lookalike Discovery

POST /v1/lookalikeFind similar creators using AI-powered analysis

Analyze Post

POST /v1/posts/analyzeAnalyze individual posts with AI insights

Posts by Creator

GET /v1/posts/by-creatorRetrieve posts from a creator’s account

Match Creators

POST /v1/matchMatch creators to campaign requirements

Brand Safety - Creators

POST /v1/brand-safety/creatorsAnalyze creators for brand safety risks

Brand Safety - Profiles

POST /v1/brand-safety/profilesAnalyze social profiles for brand risks

Brand Safety - Posts

POST /v1/brand-safety/postsAnalyze posts for brand safety concerns

Quick Start

# Search for fitness influencers
curl -X POST https://api.influship.com/v1/search \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "fitness influencers with 100k+ followers",
    "mode": "detailed",
    "filters": {
      "platform_filters": [{
        "platform": "instagram",
        "min_followers": 100000,
        "min_engagement_rate": 3
      }]
    }
  }'

Best Practices

Use Lite Mode First

Start with mode: "lite" for exploration, upgrade to detailed only when you need extended metrics

Batch Requests

Use batch endpoints (e.g., /v1/creators?creator_ids=id1,id2,id3) to reduce API calls

Implement Caching

Cache frequently accessed data to minimize costs and improve performance

Monitor Headers

Track rate limit and billing headers to optimize usage and avoid surprises

Handle Errors Gracefully

Implement exponential backoff for 429 errors and proper error handling for all status codes

Use Filters

Apply search filters to reduce result sets and save on credits

Need Help?

Quickstart Guide

Get up and running in 5 minutes

Code Examples

Real-world implementation examples

Support

Contact our support team

Overview

Endpoints

​API Reference

​Base URL

​Authentication

​Pagination

​How It Works

​Pagination Fields

​Response Format

​Success Response

​Error Response

​Response Headers

​Billing & Usage Headers

​Rate Limit Headers

​Credits & Billing

​Pricing Models

Search & Discovery

Creator Data

Content Analysis

Brand Safety & Matching

​Common Patterns

​1. Discovery → Enrichment Flow

​2. Search → Analysis Flow

​3. Lookalike Discovery

​Platform Support

​Data Concepts

​Creator vs Profile Data

Creator Data

Profile Data

​Response Modes

​Rate Limits

​By Plan

​HTTP Status Codes

​API Endpoints

Search Creators

Autocomplete

Get Creators

Get Profiles

Creator's Profiles

Lookalike Discovery

Analyze Post

Posts by Creator

Match Creators

Brand Safety - Creators

Brand Safety - Profiles

Brand Safety - Posts

​Quick Start

​Best Practices

Use Lite Mode First

Batch Requests

Implement Caching

Monitor Headers

Handle Errors Gracefully

Use Filters

​Need Help?

Quickstart Guide

Code Examples

Support

API Reference

Base URL

Authentication

Pagination

How It Works

Pagination Fields

Response Format

Success Response

Error Response

Response Headers

Billing & Usage Headers

Rate Limit Headers

Credits & Billing

Pricing Models

Common Patterns

1. Discovery → Enrichment Flow

2. Search → Analysis Flow

3. Lookalike Discovery

Platform Support

Data Concepts

Creator vs Profile Data

Response Modes

Rate Limits

By Plan

HTTP Status Codes

API Endpoints

Quick Start

Best Practices

Need Help?