Lookalike Discovery

Find creators similar to your seed profiles using AI-powered vector similarity search. The lookalike endpoint supports both creator IDs and platform usernames as seeds, with comprehensive filtering options.

Overview

The lookalike discovery feature uses advanced AI to find creators with similar characteristics to your seed profiles. It analyzes content style, audience demographics, engagement patterns, and behavioral data to identify the most relevant matches.

✅ Fully working

Supported Platforms

Currently supported platforms for seed resolution:

Instagram ✅ (Fully supported)

Future platforms (configured but not yet enabled):

TikTok (coming soon)
YouTube (coming soon)
Twitter (coming soon)

Seed Types

You can provide seeds in multiple ways:

Creator ID Seeds

Use existing creator IDs from your database:

{
  "seeds": [
    { "id": "00000000-0000-0000-0000-000000000000", "weight": 1.0 },
    { "id": "00000000-0000-0000-0000-000000000001", "weight": 0.8 }
  ]
}

Platform Username Seeds

Use social media usernames directly:

{
  "seeds": [
    { "platform": "instagram", "username": "sarahfitness", "weight": 1.0 },
    { "platform": "instagram", "username": "fitnessguru", "weight": 0.8 }
  ]
}

Mixed Seeds

Combine both approaches:

{
  "seeds": [
    { "id": "00000000-0000-0000-0000-000000000000", "weight": 1.0 },
    { "platform": "instagram", "username": "fitnessguru", "weight": 0.8 }
  ]
}

Comprehensive Filtering

Apply detailed filters to refine your lookalike results:

{
  "seeds": [...],
  "filters": {
    "platform": ["instagram"],
    "audience_size": {
      "min": 10000,
      "max": 1000000
    },
    "engagement_rate": {
      "min": 0.02,
      "max": 0.1
    },
    "verified": true,
      "location": ["US", "CA"],
    "interests": ["fitness", "wellness"]
  }
}

Filter	Type	Description	Example
`platform`	Array	Platforms to include	`["instagram"]`
`audience_size`	Object	Follower count range	`{"min": 10000, "max": 1000000}`
`engagement_rate`	Object	Engagement rate range	`{"min": 0.02, "max": 0.1}`
`verified`	Boolean	Verification status	`true`
`location`	Array	Location codes (ISO 3166-1)	`["US", "CA"]`
`interests`	Array	Basic bio text matching	`["fitness", "wellness"]`

Parameter Differences

`result_scope` vs `profile_platforms`

result_scope controls which creators are returned:

seed_platform: Only return creators who have profiles on the same platform as your seed creators
all_platforms: Return creators from any platform, regardless of seed platform

profile_platforms controls which social profiles are included for each creator:

If not specified: All profiles for each creator are returned
If specified: Only profiles from the specified platforms are included

Response Detail Levels

mode controls creator-level data detail:

lite: Basic creator info (name, bio, avatar)
detailed: Full creator data with AI recommendations

profile_mode controls profile-level data detail:

lite: Basic profile info (platform, username, follower_count)
detailed: Full profile data (engagement_rate, verified, avg_likes, etc.)

Weight System

Seed weights allow you to emphasize certain creators:

Weight 1.0: Standard importance
Weight 0.5: Half importance
Weight 2.0: Double importance
Range: 0.1 to 10.0

Higher weights make that seed more influential in the similarity calculation.

AI-Powered Similarity

The lookalike algorithm uses advanced AI techniques:

Vector Embeddings: Deep learning models analyze creator content and behavior
Multi-Factor Analysis: Content style, audience demographics, engagement patterns
AI Reranking: Final results are scored and ranked by AI for optimal relevance

Example Request

curl -X POST https://api.influship.com/v1/lookalike \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "seeds": [
      { "platform": "instagram", "username": "sarahfitness", "weight": 1.0 }
    ],
    "filters": {
      "platform": ["instagram"],
      "audience_size": { "min": 50000, "max": 500000 },
      "engagement_rate": { "min": 0.03 },
      "verified": true
    },
    "mode": "detailed",
    "result_scope": "seed_platform"
  }'

Example Response

{
  "items": [
    {
      "id": "00000000-0000-0000-0000-000000000002",
      "name": "Emma Wilson",
      "username": "emmawellness",
      "platform": "instagram",
      "similarity": 0.89,
      "engagement_rate": 0.045,
      "verified": true,
      "follower_count": 125000,
      "bio": "Wellness coach and fitness enthusiast",
      "profiles": [
        {
          "platform": "instagram",
          "username": "emmawellness",
          "follower_count": 125000,
          "engagement_rate": 0.045,
          "verified": true
        },
        {
          "platform": "tiktok",
          "username": "emmawellness",
          "follower_count": 50000,
          "engagement_rate": 0.08,
          "verified": false
        }
      ],
      "ai_recommendation": {
        "score": 0.92,
        "explanation": "High similarity to seed creator with strong engagement and fitness focus"
      }
    }
  ],
  "filtered_total": 45,
  "has_more": true,
  "next_cursor": "eyJvZmZzZXQiOjI1fQ=="
}

Response Detail Examples

Lite Mode Response (`mode: "lite"`, `profile_mode: "lite"`)

{
  "items": [
    {
      "id": "00000000-0000-0000-0000-000000000002",
      "name": "Emma Wilson",
      "avatar_url": "https://img/emma.jpg",
      "bio": "Wellness coach and fitness enthusiast",
      "profiles": [
        {
          "platform": "instagram",
          "username": "emmawellness",
          "follower_count": 125000
        },
        {
          "platform": "tiktok",
          "username": "emmawellness",
          "follower_count": 50000
        }
      ],
      "ai_recommendation": {
        "score": 0.92,
        "explanation": "High similarity to seed creator with strong engagement and fitness focus"
      }
    }
  ]
}

Detailed Mode Response (`mode: "detailed"`, `profile_mode: "detailed"`)

{
  "items": [
    {
      "id": "00000000-0000-0000-0000-000000000002",
      "name": "Emma Wilson",
      "avatar_url": "https://img/emma.jpg",
      "bio": "Wellness coach and fitness enthusiast",
      "profiles": [
        {
          "platform": "instagram",
          "username": "emmawellness",
          "follower_count": 125000,
          "engagement_rate": 0.045,
          "verified": true,
          "avg_likes": 5000,
          "posts_per_week": 3,
          "avatar_url": "https://img/emma_ig.jpg",
          "external_url": "https://emmawellness.com"
        },
        {
          "platform": "tiktok",
          "username": "emmawellness",
          "follower_count": 50000,
          "engagement_rate": 0.08,
          "verified": false,
          "avg_likes": 2000,
          "posts_per_week": 5,
          "avatar_url": "https://img/emma_tiktok.jpg"
        }
      ],
      "ai_recommendation": {
        "score": 0.92,
        "explanation": "High similarity to seed creator with strong engagement and fitness focus"
      }
    }
  ]
}

Platform Filtering Example (`profile_platforms: ["instagram"]`)

{
  "items": [
    {
      "id": "00000000-0000-0000-0000-000000000002",
      "name": "Emma Wilson",
      "avatar_url": "https://img/emma.jpg",
      "bio": "Wellness coach and fitness enthusiast",
      "profiles": [
        {
          "platform": "instagram",
          "username": "emmawellness",
          "follower_count": 125000,
          "engagement_rate": 0.045,
          "verified": true
        }
        // TikTok profile excluded due to profile_platforms filter
      ],
      "ai_recommendation": {
        "score": 0.92,
        "explanation": "High similarity to seed creator with strong engagement and fitness focus"
      }
    }
  ]
}

Pagination

Use cursor-based pagination to retrieve large result sets:

# First page
curl -H "X-API-Key: YOUR_KEY" \
  "https://api.influship.com/v1/lookalike?limit=25"

# Next page using cursor from previous response
curl -H "X-API-Key: YOUR_KEY" \
  "https://api.influship.com/v1/lookalike?limit=25&cursor=eyJvZmZzZXQiOjI1fQ=="

Error Handling

Creator Not Found (404)

{
  "error": {
    "code": "creator_not_found",
    "message": "Creator not found: instagram/fitnessguru",
    "request_id": "req_123"
  }
}

Invalid Seed (400)

{
  "error": {
    "code": "invalid_seed",
    "message": "Username must be between 1 and 30 characters",
    "request_id": "req_123"
  }
}

Unsupported Platform (400)

{
  "error": {
    "code": "invalid_seed",
    "message": "Unsupported platform: tiktok. Currently supported: instagram",
    "request_id": "req_123"
  }
}

Pricing

Base Cost: 0.1 credits per request
Per Seed: 0.05 credits per seed creator
Filtering: No additional cost for comprehensive filtering
AI Reranking: Included in base cost

Example: 2 seeds + detailed filtering = 0.2 credits

Best Practices

Seed Selection

Choose 2-5 diverse seed creators for best results
Use creators with clear, consistent content themes
Include both high and medium engagement creators

Filtering Strategy

Start with broad filters, then narrow down
Use audience size ranges to match your campaign goals
Filter by engagement rate to ensure quality

Performance Tips

Use mode: "lite" for faster responses when detailed data isn’t needed
Set appropriate limit values (25-50 is optimal)
Cache results when possible to reduce API calls

Use Cases

Campaign Expansion

Find creators similar to your best-performing influencers to expand your reach.

Competitor Analysis

Discover creators with similar audiences to your competitors’ top performers.

Niche Discovery

Identify creators in specific niches by using niche-specific seed creators.

Audience Matching

Find creators with audiences similar to your target demographic.

Next Steps

API Reference

Complete endpoint documentation

Examples

Code samples and tutorials

Authentication

API key setup

Support

Get help

Get Started

Essentials

Authentication

Best Practices

Advanced Topics

​Lookalike Discovery

​Overview

​Supported Platforms

​Seed Types

​Creator ID Seeds

​Platform Username Seeds

​Mixed Seeds

​Comprehensive Filtering

​Filter Options

​Parameter Differences

​result_scope vs profile_platforms

​Response Detail Levels

​Weight System

​AI-Powered Similarity

​Example Request

​Example Response

​Response Detail Examples

​Lite Mode Response (mode: "lite", profile_mode: "lite")

​Detailed Mode Response (mode: "detailed", profile_mode: "detailed")

​Platform Filtering Example (profile_platforms: ["instagram"])

​Pagination

​Error Handling

​Creator Not Found (404)

​Invalid Seed (400)

​Unsupported Platform (400)

​Pricing

​Best Practices

​Seed Selection

​Filtering Strategy

​Performance Tips

​Use Cases

​Campaign Expansion

​Competitor Analysis

​Niche Discovery

​Audience Matching

​Next Steps

API Reference

Examples

Authentication

Support

Lookalike Discovery

Overview

Supported Platforms

Seed Types

Creator ID Seeds

Platform Username Seeds

Mixed Seeds

Comprehensive Filtering

Filter Options

Parameter Differences

`result_scope` vs `profile_platforms`

Response Detail Levels

Weight System

AI-Powered Similarity

Example Request

Example Response

Response Detail Examples

Lite Mode Response (`mode: "lite"`, `profile_mode: "lite"`)

Detailed Mode Response (`mode: "detailed"`, `profile_mode: "detailed"`)

Platform Filtering Example (`profile_platforms: ["instagram"]`)

Pagination

Error Handling

Creator Not Found (404)

Invalid Seed (400)

Unsupported Platform (400)

Pricing

Best Practices

Seed Selection

Filtering Strategy

Performance Tips

Use Cases

Campaign Expansion

Competitor Analysis

Niche Discovery

Audience Matching

Next Steps