# TikTok Image-based AI Search

Search for influencers using an image based query (along with other filters) and you will get influencers who have posted content similar to the query image. This API has a fixed 1 RPS limit for searches. Each resulting profile costs 0.025 credits.

Endpoint: POST /ai/tiktok/image-search
Security: accessToken

## Request fields (application/json):

  - `page` (number)
    Page number. The offset is calculated as page * pageSize, so changing pageSize between pages will shift the window and may cause duplicate or missed results.

  - `pageSize` (number)
    Number of results per page. Each result costs 0.025 credits.

  - `filters` (object)
    Additional filters to refine the search results
    Example: {"followersCount":{"min":13000},"gender":"FEMALE","lastPostedInDays":90,"accountType":"creator","language":"en","age":{"min":"18"},"engagementRate":{"min":0.04},"hasEmail":true,"maxPostAgeMonths":3}

  - `filters.followersCount` (object)
    Filter by followers count
    Example: {"min":13000}

  - `filters.followersCount.min` (number)
    Minimum followers count. Number will be approximated to the nearest range lower or equal to the given number. Ranges are: 1000, 3000, 5000, 10000, 15000, 20000, 25000, 35000, 50000, 75000, 100000, 125000, 150000, 175000, 200000, 250000, 300000, 350000, 500000, 1000000, 2000000, 3000000.
    Example: 13000

  - `filters.followersCount.max` (number)
    Maximum followers count. Number will be approximated to the nearest range higher or equal to the given number. Ranges are: 1000, 3000, 5000, 10000, 15000, 20000, 25000, 35000, 50000, 75000, 100000, 125000, 150000, 175000, 200000, 250000, 300000, 350000, 500000, 1000000, 2000000, 3000000.

  - `filters.locations` (array)
    Filter by locations (use Locations dictionary endpoint to get the location IDs)

  - `filters.gender` (string)
    Filter by gender; KNOWN -> male or female, UNKNOWN -> gender neutral
    Enum: "MALE", "FEMALE", "KNOWN", "UNKNOWN"

  - `filters.lastPostedInDays` (number)
    Filter by influencers with latest post date, in days. P.S. we update profiles every 4 weeks and this lag should be considered when using this field.
    Example: 90

  - `filters.accountType` (string)
    Filter by account type
    Enum: "creator", "brand"

  - `filters.language` (string)
    Filter by language (use Languages dictionary endpoint to get the language IDs)
    Example: "en"

  - `filters.age` (object)
    Filter by age range
    Example: {"min":"18"}

  - `filters.age.min` (string)
    Minimum age range
    Enum: "13", "18", "25", "35", "45", "65"

  - `filters.age.max` (string)
    Maximum age range
    Enum: "18", "25", "35", "45", "65"

  - `filters.engagementRate` (object)
    Filter by engagement rate
    Example: {"min":0.04}

  - `filters.engagementRate.min` (number)
    Minimum engagement rate (in percentage, 0.01 = 1%)
    Example: 0.04

  - `filters.hasEmail` (boolean)
    Filter by whether the influencer has an email
    Example: true

  - `filters.brands` (array)
    Filter by brands (Use AI search's Brand Dictionary endpoint to get the brand names. P.S. this is a different endpoint than existing Brand Dictionary endpoint).

  - `filters.username` (string)
    Username to search for

  - `filters.maxPostAgeMonths` (number)
    Filter by the maximum age of the posts in months. Used to request more recent posts.
    Enum: 3, 6, 9, 12

  - `filters.contentType` (string)
    Filter by content type. Allowed values: video, image. If not provided, both video and image content will be returned.
    Enum: "video", "image"

  - `imageType` (string, required)
    Image type
    Enum: "image/jpeg", "image/png", "image/webp"

  - `base64Image` (string, required)
    Image (base64 encoded), max size 5MB

## Response 200 fields (application/json):

  - `error` (boolean)
    If there is an error

  - `total` (number, required)
    Total number of profiles matching the search query

  - `profiles` (array, required)
    List of influencer profiles matching the search query and filters

  - `profiles.userId` (string)
    User ID
    Example: "173560420"

  - `profiles.fullName` (string)
    Full name
    Example: "Instagram"

  - `profiles.username` (string, required)
    Username
    Example: "instagram"

  - `profiles.profilePicture` (string, required)
    Profile Picture
    Example: "https://imgigp.modash.io/22159423_1794482210565499_9190891265074397184_n.jpg"

  - `profiles.followersCount` (number, required)
    Followers count
    Example: 313560626

  - `profiles.engagementRate` (number, required)
    Engagement rate
    Example: 0.01

  - `profiles.matchedPosts` (array, required)
    Posts ordered by relevance to the search query

  - `profiles.matchedPosts.id` (string, required)
    Post ID

  - `profiles.matchedPosts.url` (string, required)
    Post URL

  - `profiles.matchedPosts.thumbnail` (string, required)
    Post thumbnail URL

  - `profiles.matchedPosts.stats` (object, required)
    Post statistics

  - `profiles.matchedPosts.stats.likesCount` (number, required)
    Likes count; -1 if likes count is hidden

  - `profiles.matchedPosts.stats.commentsCount` (number, required)
    Comments count; -1 if comments count is hidden

  - `profiles.matchedPosts.stats.sharesCount` (number, required)
    Shares count

  - `profiles.matchedPosts.stats.playsCount` (number, required)
    Plays count

  - `profiles.matchedPosts.stats.collectsCount` (number, required)
    Collects count

  - `profiles.recentPosts` (array, required)
    Recent posts (not necessarily relevant to the search query). P.S. we update profiles every 4 weeks and this lag should be considered when using this field.

  - `profiles.accountCategory` (string, required)
    Account category
    Example: "Sportsperson / Digital creator etc."