# Instagram 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. Default 1 RPS. Each resulting profile costs 0.025 credits.

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

## Request fields (application/json):

  - `page` (number)
    Page number (0-indexed). The offset is calculated as page * pageSize, so changing pageSize between pages will shift the window and may cause duplicate or missed results. The total number of results that can be accessed is limited to 1500 — that is, (page + 1) * pageSize must not exceed 1500. Requests beyond this limit will receive a 400 error.

  - `pageSize` (number)
    Number of results per page. Each result costs 0.025 credits. The maximum total depth of results (page * pageSize + pageSize) is 1500. For example, with pageSize 50 you can paginate up to page 29.

  - `filters` (object)
    Additional filters to refine the search results
    Example: {"followersCount":{"min":10000},"gender":"MALE","lastPostedInDays":90,"accountType":"creator","language":"es","age":{"min":"18"},"engagementRate":{"min":0.01},"postingFrequency":{"min":2},"followersGr…

  - `filters.followersCount` (object)
    Filter by followers count

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

  - `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. 'creator' is a backwards-compatible alias for 'individual_creator' and 'group_creator'. 'individual_creator' - a single identifiable person is clearly the face and voice; 'group_creator' - two or more identifiable individuals as co-equal faces; 'brand' - a business, organization, media entity, or professional service portfolio; 'anonymous_content' - no identifiable person or organization, curated/aggregated/themed content.
    Enum: "creator", "individual_creator", "group_creator", "brand", "anonymous_content"

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

  - `filters.age` (object)
    Filter by age range

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

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

  - `filters.postingFrequency` (object)
    Filter by average monthly posting frequency

  - `filters.postingFrequency.min` (number)
    Minimum average posts per 30-day month
    Example: 4

  - `filters.postingFrequency.max` (number)
    Maximum average posts per 30-day month
    Example: 20

  - `filters.viewsCount` (object)
    Filter by average per-post view count (median or mean)

  - `filters.viewsCount.min` (number)
    Minimum average per-post view 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.

  - `filters.viewsCount.max` (number)
    Maximum average per-post view 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.viewsCount.calculationMethod` (string)
    Whether to filter on median or mean per-post view count (from in-house post_views_stats over the last 60 days).
    Enum: "median", "average"

  - `filters.followersGrowthRate` (object)
    Filter by followers growth rate over the selected interval. At least one of min or max is required. Influencers without a growth rate for that interval are excluded.
    Example: {"interval":"i3months","min":0.05}

  - `filters.followersGrowthRate.interval` (string)
    Growth window to filter and report on. Defaults to the trailing six months.
    Enum: "i1month", "i2months", "i3months", "i4months", "i5months", "i6months"

  - `filters.followersGrowthRate.min` (number)
    Minimum followers growth rate over the interval, as a decimal fraction (0.05 = 5% growth). Negative values match shrinking accounts.
    Example: 0.05

  - `filters.followersGrowthRate.max` (number)
    Maximum followers growth rate over the interval, as a decimal fraction (0.05 = 5% growth). Negative values match shrinking accounts.
    Example: 0.5

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

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

  - `filters.textTags` (array)
    Filter by influencers who have used the defined hashtags or mentions in their posts. Values should be without # or @ prefix.
    Example: [{"type":"hashtag","value":"carsofinstagram"},{"type":"mention","value":"topgear"}]

  - `filters.textTags.type` (string, required)
    Type of text tag
    Enum: "hashtag", "mention"

  - `filters.textTags.value` (string, required)
    Value of the text tag (without # or @ prefix)
    Example: carsofinstagram

  - `filters.textTags.mode` (string)
    Whether to include or exclude posts with this tag. Defaults to include.
    Enum: "include", "exclude"

  - `filters.bio` (any)
    Full-text search within influencer biography. Provide a single phrase, or up to 10 phrases; a profile matches if any phrase is found.
    Example: ["travel photographer","landscape photography"]

  - `filters.keywords` (any)
    Full-text search within post captions (Instagram/TikTok caption text, YouTube title/description). Provide a single phrase, or up to 10 phrases; a profile matches if any phrase is found.
    Example: ["supercars","exotic cars"]

  - `filters.lists` (object)
    Filter by AI Search lists (create/manage via /ai/lists). Currently exactly one list ID is supported; support for multiple lists is in the works. include: profiles in the list; exclude: profiles not in the list. List platform must match the search platform.
    Example: {"listIds":["a1b2c3d4e5f6789012345678abcdef01"],"mode":"exclude"}

  - `filters.lists.listIds` (array, required)
    AI Search list IDs (from POST /ai/lists). Currently exactly one list ID is supported for include/exclude; support for multiple lists is in the works.
    Example: ["a1b2c3d4e5f6789012345678abcdef01"]

  - `filters.lists.mode` (string, required)
    include: profiles in the list; exclude: profiles not in the list
    Enum: "include", "exclude"

  - `filters.audience` (object)
    Filter by Audience

  - `filters.audience.credibility` (number)
    Filter by Audience Credibility. The value is the inverse of fake followers, meaning 25% fake followers would translate to 0.75 of audience credibility.

  - `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
    Example: false

  - `total` (number, required)
    Approximate number of profiles matching the search query. This is estimated from similarity score distribution and can exceed how many profiles pagination can actually return.

  - `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 as a percentage (0.71 = 0.71%)
    Example: 0.71

  - `profiles.postingFrequency` (number, required)
    Average posts per 30-day month
    Example: 12

  - `profiles.viewsCountMedian` (number)
    Median per-post view count over the last 60 days
    Example: 25000

  - `profiles.viewsCountMean` (number)
    Mean per-post view count over the last 60 days
    Example: 32000

  - `profiles.followersGrowthRate` (number)
    Followers growth rate over the interval requested through the followersGrowthRate filter, as a decimal fraction (0.05 = 5% growth). Defaults to the trailing six months when the filter is not used, and is omitted when no growth rate is available for that interval.
    Example: 0.05

  - `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.playsCount` (number, required)
    Plays 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.