Search Creators

Search for creators across multiple platforms with advanced filtering, faceted search, and full-text capabilities.

Endpoint

POST /api/creators/search

Request

Headers

Authorization

string

required

Bearer token for authentication

Content-Type

string

required

Must be application/json

Body Parameters

query

string

Search query for creator name, bio, or tags

filters

object

Optional filters to narrow down results

Show Filter Options

platform

string

Filter by platform: youtube, twitter, instagram, tiktok, linkedin

Response

success

boolean

Indicates if the request was successful

data

object

Show Search Results

creators

array

Array of creator objects matching the search criteria

Show Creator Object

string

Unique creator identifier

name

string

Creator’s display name

bio

string

Creator’s biography

profileImageUrl

string

URL to profile image

Examples

Basic Search

TypeScript
JavaScript
cURL

interface SearchOptions {
  query: string;
  filters?: {
    platform?: string;
    category?: string;
    tags?: string[];
    minFollowers?: number;
    maxFollowers?: number;
    minEngagement?: number;
    maxEngagement?: number;
    verified?: boolean;
  };
  sort?: {
    by: 'relevance' | 'followers' | 'engagement' | 'recent';
    order: 'asc' | 'desc';
  };
  pagination?: {
    page: number;
    limit: number;
  };
  searchType?: 'fulltext' | 'fuzzy' | 'combined';
}

const response = await fetch('https://your-domain.com/api/creators/search', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    query: 'tech influencer',
    filters: {
      platform: 'tiktok',
      minFollowers: 10000,
      verified: true
    },
    sort: {
      by: 'engagement',
      order: 'desc'
    },
    pagination: {
      page: 1,
      limit: 20
    }
  })
});

const data = await response.json();
console.log(`Found ${data.data.total} creators`);

const searchCreators = async (options) => {
  const response = await fetch('https://your-domain.com/api/creators/search', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(options)
  });

  return await response.json();
};

// Search for gaming creators
const results = await searchCreators({
  query: 'gaming',
  filters: {
    category: 'gaming',
    minEngagement: 50
  },
  sort: {
    by: 'followers',
    order: 'desc'
  }
});

console.log(results.data.creators);

curl -X POST https://your-domain.com/api/creators/search \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "tech influencer",
    "filters": {
      "platform": "tiktok",
      "minFollowers": 10000,
      "verified": true
    },
    "sort": {
      "by": "engagement",
      "order": "desc"
    },
    "pagination": {
      "page": 1,
      "limit": 20
    }
  }'

Multi-Platform Search

// Search creators with presence on multiple platforms
const response = await fetch('https://your-domain.com/api/creators/search', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    query: 'lifestyle',
    filters: {
      tags: ['fashion', 'beauty', 'wellness'],
      minFollowers: 50000
    },
    sort: {
      by: 'engagement',
      order: 'desc'
    }
  })
});

const { data } = await response.json();

// Filter creators with multiple platform presence
const multiPlatformCreators = data.creators.filter(creator => 
  Object.keys(creator.platforms).length >= 3
);

Fuzzy Search

// Use fuzzy search for name variations
const response = await fetch('https://your-domain.com/api/creators/search', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    query: 'jon doe', // Will match "John Doe", "Jon Dough", etc.
    searchType: 'fuzzy',
    pagination: {
      page: 1,
      limit: 10
    }
  })
});

Response Example

{
  "success": true,
  "data": {
    "creators": [
      {
        "id": "creator_123",
        "name": "Tech Guru",
        "bio": "Technology enthusiast and educator",
        "profileImageUrl": "https://example.com/avatar.jpg",
        "category": "tech",
        "tags": ["programming", "ai", "web3"],
        "isVerified": true,
        "metrics": {
          "totalReach": 250000,
          "engagementScore": 87.5,
          "engagementRate": 5.2,
          "contentFrequency": 5,
          "audienceQuality": 92
        },
        "platforms": {
          "tiktok": {
            "followers": 150000,
            "videos": 342,
            "likes": "5200000",
            "engagement": 6.1
          },
          "youtube": {
            "subscribers": 100000,
            "videos": 156,
            "views": "8500000",
            "engagement": 4.3
          }
        },
        "lastSync": "2026-03-06T10:30:00Z",
        "syncStatus": "COMPLETED"
      }
    ],
    "total": 1247,
    "facets": {
      "categories": [
        { "value": "tech", "count": 456 },
        { "value": "gaming", "count": 312 },
        { "value": "lifestyle", "count": 289 }
      ],
      "platforms": [
        { "value": "tiktok", "count": 892 },
        { "value": "instagram", "count": 743 },
        { "value": "youtube", "count": 621 }
      ],
      "tags": [
        { "value": "programming", "count": 234 },
        { "value": "ai", "count": 189 },
        { "value": "tutorial", "count": 156 }
      ]
    },
    "suggestions": [
      "tech influencer",
      "tech reviewer",
      "tech education"
    ]
  }
}

Error Responses

Invalid Search Type

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid searchType. Must be 'fulltext', 'fuzzy', or 'combined'"
  }
}

Pagination Out of Bounds

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Limit must be between 1 and 100"
  }
}

Implementation Details

The search service is implemented in /lib/services/creator-search.ts:42:

class CreatorSearchService {
  async search(options: SearchOptions): Promise<SearchResult> {
    // Full-text search using PostgreSQL
    const fullTextResults = await prisma.$queryRaw<Array<{ id: string; rank: number }>>\`
      SELECT id, rank FROM search_creators(${query}, ${limit * 2})
    \`;
    
    // Fuzzy search for name variations
    const fuzzyResults = await prisma.$queryRaw<Array<{ id: string; similarity: number }>>\`
      SELECT id, similarity FROM fuzzy_search_creators(${query}, 0.3, ${limit * 2})
    \`;
    
    // Combined results with deduplication
    // ...
  }
}

Overview

Creator APIs

Discovery APIs

Budget & Monitoring

Search Creators

Search Creators

Endpoint

Request

Headers

Body Parameters

Response

Examples

Basic Search

Multi-Platform Search

Fuzzy Search

Response Example

Error Responses

Invalid Search Type

Implementation Details

Next Steps

Get Profile

Track Metrics

Build docs developers (and LLMs) love

Overview

Creator APIs

Discovery APIs

Budget & Monitoring

​Search Creators

​Endpoint

​Request

​Headers

​Body Parameters

​Response

​Examples

​Basic Search

​Multi-Platform Search

​Fuzzy Search

​Response Example

​Error Responses

​Invalid Search Type

​Pagination Out of Bounds

​Implementation Details

​Next Steps

Get Profile

Track Metrics

Build docs developers (and LLMs) love

Search Creators

Endpoint

Request

Headers

Body Parameters

Response

Examples

Basic Search

Multi-Platform Search

Fuzzy Search

Response Example

Error Responses

Invalid Search Type

Pagination Out of Bounds

Implementation Details

Next Steps