# YouTube Text-based AI Search

Search for influencers using a text based query i.e. "woman with curly hair lifting weights" (along with other filters). This API has a fixed 1 RPS limit for searches. Each successful request consumes 0.15 credits.

Endpoint: POST /ai/youtube/text-search
Security: accessToken

## Request fields (application/json):

  - `page` (number)
    Page number, each page contains max. 6 results

  - `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"

  - `query` (string)
    Example: woman with curly hair lifting weights. Queries can be sent in any language, but English yields the best results. Limit: 8192 characters or 512 words. If omitted, results are sorted by follower count.
    Example: "woman with curly hair lifting weights"

## 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.viewsCount` (number, required)
    Views 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.