Configuring Advanced Search Filters and Examples - CreatorDB Documentation Center

Select a tab to view the specific filter configurations and examples for that particular platform or brand.

YouTube
Instagram
TikTok
Brands

Using filters in YouTube advanced search

Search for YouTube creators using various filter options.

Using subscribers as a filter

Filter YouTube creators by subscriber count.

Using average views as a filter

Filter YouTube creators by average views.

Using the country as a filter

Filter YouTube creators by country.

Using content as a filter

Filter YouTube creators by content.

Using the target audience as a filter

Filter YouTube creators by target audience.

Configuring filters for YouTube advanced search

This page lists the available filterKey options for the YouTube Advanced Search API, including the data types, examples, and notes on data sorting and availability. You can use multiple filterKey to narrow your search criteria to find the most relevant YouTube creators. By default, the API lists YouTube creator search results by their CreatorDB ranking score (ranking.score filter) in descending order.

Available `filterKey` and `sortBy` options

The table below lists the available filterKey options with the YouTube Advanced Search API. Each entry includes the expected data type and an example value and indicates whether the filterKey supports sorting or is only available for specific data APIs.

Column definitions

Supports sorting

Indicates whether this field can also be used as a sortBy parameter. When the field is checkmarked, it supports sorting search results by that parameter in ascending or descending order.

The sorting behavior depends on the data type— for example, strings are sorted alphabetically.

Returned only in youtubeDetail API

When this column is checkmarked, it indicates the field is only returned in the youtubeDetail API response.For example, when you use the mainLanguage filter to make an Advanced Search API call, it will return valid creator IDs. However, the mainLanguage field will only appear in the youtubeDetail API response and not in the youtubeBasic API response.

Available Filter	Type	Example	Description	Supports sorting	Returned only in youtubeDetail API
avgCommentReplyRatio1Y	`number`	0.001851851852	The creator’s average reply rate to the top 20 comments on each video (up to 800 videos).	✅	⬜
avgCommentReplyRatioR20	`number`	0	The creator’s average reply rate to the top 20 comments on each of their most recent 20 videos.	✅	⬜
avgComments1Y	`number`	6286	The average comments per video, calculated from up to the creator’s most recent 800 videos.	✅	⬜
avgCommentsR20	`number`	6328	The average comments per video, calculated from the creator’s most recent 20 videos.	✅	⬜
avgLength1Y	`number`	579	The average video length (in seconds), calculated from up to the creator’s most recent 800 videos.	✅	⬜
avgLengthR20	`number`	581.9444444	The average video length (in seconds), calculated from the creator’s most recent 20 videos.	✅	⬜
avgLikes1Y	`number`	75075	The average likes per video, calculated from up to the creator’s most recent 800 videos.	✅	⬜
avgLikesR20	`number`	61056	The average likes per video, calculated from the creator’s most recent 20 videos.	✅	⬜
avgSelfCommentRatio1Y	`number`	0.01925925926	The creator’s average self-comment rate to the top 20 comments on each of their most recent videos (up to 800 videos).(A self-comment refers to a comment made by the creator on their own video.)	✅	⬜
avgSelfCommentRatioR20	`number`	0.01388888889	The creator’s average self-comment rate to the top 20 comments on each of their most recent 20 videos. (A self-comment refers to a comment made by the creator under their own video.)	✅	⬜
avgViews1Y	`number`	2038892	The average views per video, calculated from up to the creator’s most recent 800 videos.	✅	⬜
avgViewsR20	`number`	1367115	The average views per video, calculated from the creator’s most recent 20 videos.	✅	⬜
country	`string` or `string [ ]`	USA or [country1, country2, …]	The country associated with the YouTube creator, represented in ISO 3166-1 alpha-3 format. For details, see Country Codes.	✅	⬜
creationDate	`number`	1499184000000	The channel’s creation time, represented as a Unix timestamp in milliseconds. If the creator hides this information, the value will be shown as `0`.	✅	✅
demographic.avgAge	`number`	30.15	Average age of the YouTube creator’s audience.	✅	✅
demographic.genderFemaleRatio	`number`	0.44	The proportion of females in the YouTube creator’s audience.	✅	✅
demographic.genderMaleRatio	`number`	0.52	The proportion of males in the YouTube creator’s audience.	✅	✅
demographic.mainCountry	`string`	USA	The country that represents the largest proportion of the YouTube creator’s audience. For details, see Country Codes.	✅	✅
demographic.mainCountryRatio	`number`	0.55	The percentage of the creator’s audience from the country with the highest audience share.	✅	✅
engageRate1Y	`number`	0.03990380683	The average engagement rate per video, calculated from videos uploaded in the past year (up to 800 videos). Engagement rate is calculated as [ (likes + comments) / views].	✅	⬜
engageRateR20	`number`	0.04928875159	The average engagement rate per video, calculated from the creator’s most recent 20 videos. Engagement rate is calculated as \ [(likes + comments) / views].	✅	⬜
gAvgViewsR20	`number`	0.1331395447	The 30-day growth rate of avgViewsR20, which represents the average number of views per video calculated from the creator’s most recent 20 videos.	✅	⬜
gEngageRateR20	`number`	-0.0174686013	The 30-day growth rate of engageRateR20, which represents the average engagement rate per video calculated from the creator’s most recent 20 videos.	✅	⬜
gSubscribers	`number`	0.007462686567	The 30-day growth rate of the creator’s subscriber count.	✅	⬜
gTotalViews	`number`	0.005777711439	The 30-day growth rate of the creator’s total channel views.	✅	⬜
hasEmail	`boolean`	TRUE	Indicates whether an email address for the YouTube creator is available in the CreatorDB database. Returns `TRUE` if the creator’s email is available. Otherwise, it returns `FALSE`.	⬜	⬜
lastVideoUploadTime	`number`	1749875118000	The upload time of the creator’s latest video, represented as a Unix timestamp in milliseconds.	✅	⬜
mainCategory	`string`	Gaming	The most frequent video category (as defined by YouTube) among up to 800 videos. For details, see YouTube Channel Categories.	✅	✅
mainCategoryRatio	`number`	1	The percentage of videos in the most frequent YouTube-defined category, calculated from up to the creator’s most recent 800 videos.	✅	✅
mainLanguage	`string` or `string [ ]`	eng or [mainLanguage1, mainLanguage2, …]	The main language used in the creator’s videos, represented in ISO 639-3 format. For details, see Language Codes.	✅	✅
niche	`string`	id_roblox_Gaming or gaming	Represents unified content themes identified by CreatorDB’s AI model, which analyzes and groups keywords, hashtags, and tags used by creators. To get valid niche values for filters, call the Get Topic and Niche Table API.	⬜	⬜
ranking.avgViews	`number`	0.996710917	The percentile rank of this channel’s `avgViews` compared to all YouTube channels in CreatorDB’s database. A value closer to `1` indicates better performance relative to others.	✅	⬜
ranking.engage	`number`	0.7545818692	The percentile rank of this channel’s engagement rate compared to all YouTube channels in CreatorDB’s database. A value closer to `1` indicates stronger performance.	✅	✅
ranking.gAvgViews	`number`	0.8751185946	The percentile rank of this channel’s `avgViews` growth rate compared to all YouTube channels in CreatorDB’s database. A value closer to `1` indicates faster growth relative to others.	✅	✅
ranking.gEngage	`number`	0.5036764884	The percentile rank of this channel’s engagement rate growth compared to all YouTube channels in CreatorDB’s database. A value closer to `1` indicates stronger growth performance.	✅	✅
ranking.gSubs	`number`	0.7108511926	The percentile rank of this channel’s subscriber growth rate compared to all YouTube channels in CreatorDB’s database. A value closer to `1` indicates faster subscriber growth.	✅	✅
ranking.score	`number`	95.93343033	The percentile rank based on a composite score calculated by CreatorDB, derived from six key metrics: engagement rate, engagement growth, average views, view growth, subscriber count, and subscriber growth. The score ranges from `0` to `100`.	✅	✅
ranking.subs	`number`	0.9993448323	The percentile rank of this channel’s subscriber count compared to all YouTube channels in CreatorDB’s database. A value closer to `1` indicates higher subscriber performance relative to others.	✅	✅
subscribers	`number`	13500000	The current total number of subscribers for the YouTube channel.	✅	⬜
topic	`string`	id_freegames_Gaming or gaming	Content categories generated by CreatorDB’s AI model, classifying creators into about 400 dynamic themes based on their content. To get valid topic values for filters, call the Get Topic and Niche Table API.	⬜	⬜
totalViews	`number`	11814627540	The total number of views across all videos uploaded on the creator’s channel.	✅	⬜
videos	`number`	2665	The total number of videos uploaded on the creator’s channel.	✅	⬜
videosIn30Days	`number`	13	The number of videos the creator uploaded in the past 30 days.	✅	✅
videosIn90Days	`number`	35	The number of videos the creator uploaded in the past 90 days.	✅	✅

Using subscribers as a filter in YouTube advanced search

The examples below demonstrate some common YouTube subscriber filter configurations.

By default, CreatorDB will list search results in descending order.

Filtering subscribers with a minimum value

By specifying greater than (> ) as the operation value, you can search for YouTube creators with a minimum number of subscribers. The following example will search the CreatorDB database for five creators with at least 100 subscribers and list their YouTube ID in descending order.

Request example
Response example

curl --request POST \
--url https: //dev.creatordb.app/v2/youtubeAdvancedSearch \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'apiId: YOUR_API_KEY' \
--data '{
"offset": 0,
"sortBy": "subscribers"
"maxResults": 5,
"desc": true,
"filters": [
   {
       "filterKey": "subscribers",
       "op": ">",
       "value": 100
   }
]
}'

{
 "data": [
     "UCX6OQ3DkcsbYNE6H8uQQuVA",
     "UCq-Fj5jknLsUf-MWSy4_brA",
     "UCbCmjCuTUZos6Inko4u57UQ",
     "UCpEhnqL0y41EpW2TvWAHD7Q",
     "UCvlE5gTbOvjiolFlEm-c_Ow",
 ],
 "quotaUsed": 1,
 "quotaUsedTotal": 206,
 "remainingPlanCredit": 0,
 "remainingPrepurchasedCredit": 99794,
 "timestamp": 1750132895538,
 "error": "",
 "success": true
}

Filtering subscribers with a maximum value

By specifying less than (< ) as the operation value, you can search for YouTube creators with a maximum number of subscribers. The following example will search the CreatorDB database for five creators with less than 1,000 subscribers and list their YouTube ID in descending order.

Request example
Response example

curl --request POST \
--url https: //dev.creatordb.app/v2/youtubeAdvancedSearch \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'apiId: YOUR_API_KEY' \
--data '{
{
"offset": 0,
"sortBy": "subscribers"
"maxResults": 5,
"desc": true,
"filters": [
   {
       "filterKey": "subscribers",
       "op": "<",
       "value": 1000
   }
],     
}
}

{
"data": [
"UCm_PX2OZkrJ8lxw26vj8Mmw",
"UC9KpqCDOeVjAWyE6xUiqQqA",
"UC-S2zuisg99SPhRtcx4m4eg",
"UCVoEE32iBywlEXPjFtU9b-g",
"UCRsikgmMLccKkZDGPvMHw2A",
],
"quotaUsed": 1,
"quotaUsedTotal": 207,
"remainingPlanCredit": 0,
"remainingPrepurchasedCredit": 99793,
"timestamp": 1750141319610,
"error": "",
"success": true
}

Filtering subscribers within a range

You can specify the range in advanced search filters by using the filter operations greater than (>) and less than (<). For example, the request sample below will return 5 YouTube IDs with 10,000 to 100,000 subscribers.

Request example
Response example

curl --request POST \
--url https://dev.creatordb.app/v2/youtubeAdvancedSearch \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'apiId: YOUR_API_KEY' \
--data '{
"offset": 0,
"sortBy": "subscribers",
"maxResults": 5,
"desc": true,
"filters": [
{
  "filterKey": "subscribers",
  "op": ">",
  "value": 10000
}
,
 {
  "filterKey": "subscribers",
  "op": "<",
  "value": 100000
}
]
}'

{  
"data": [  
   "UCny4cF2o6VYsgogaVnIQcBw",  
   "UCmw08KiLsMrRKS7dv-uoN2g",  
   "UCpWc-iaztQGtpl93EjqlIkg",  
   "UCgbSv7\_0wcfZRYPQ2BltCKg",  
   "UC8kMd3M-tcbDw72bryZEuLA"  
],  
"quotaUsed": 1,  
"quotaUsedTotal": 208,  
"remainingPlanCredit": 0,  
"remainingPrepurchasedCredit": 99792,  
"timestamp": 1750142973600,  
"error": "",  
"success": true  
}

Using average views as a filter in YouTube advanced search

CreatorDB provides two average views filter options, avgViews1Y and avgViewsR20. The examples below use avgViews1Y to demonstrate common settings.

Filtering by `avgViews1Y` with a minimum value

Use the > operator to search for YouTube creators with a minimum average view count for up to 800 videos uploaded in the past year. For example, the API request below finds five creators with at least 10,000 average views in the last year and lists their YouTube IDs in descending order of subscribers.

Request example
Response example

curl --request POST \  
--url https: //dev.creatordb.app/v2/youtubeAdvancedSearch \\  
--header 'Accept: application/json' \\  
--header 'Content-Type: application/json' \\  
--header 'apiId: YOUR\_API\_KEY' \\  
--data '{  
  "desc": true,  
  "filters": [  
      {  
          "filterKey": "avgViews1Y",  
          "op": ">",  
          "value": 10000  
      }  
  ],  
  "maxResults": 5,  
  "offset": 0,  
  "sortBy": "subscribers"  
}

{  
   "data": [  
       "UCX6OQ3DkcsbYNE6H8uQQuVA",  
       "UCq-Fj5jknLsUf-MWSy4_brA",  
       "UCbCmjCuTUZos6Inko4u57UQ",  
       "UCpEhnqL0y41EpW2TvWAHD7Q",  
       "UCvlE5gTbOvjiolFlEm-c_Ow"  
   ],  
   "quotaUsed": 1,  
   "quotaUsedTotal": 211,  
   "remainingPlanCredit": 0,  
   "remainingPrepurchasedCredit": 99789,  
   "timestamp": 1750148393860,  
   "error": "",  
   "success": true  
}

Filtering by `avgViews1Y` with a maximum value

Use the < operator to search for YouTube creators with a maximum average view count for up to 800 videos uploaded in the past year. For example, the API request below finds five creators with less than 100,000 average views in the last year and lists their YouTube IDs in descending order of subscribers.

Request example
Response example

curl --request POST \ 
--url https: //dev.creatordb.app/v2/youtubeAdvancedSearch \
--header 'Accept: application/json' \ 
--header 'Content-Type: application/json' \  
--header 'apiId: YOUR_API_KEY' \
--data '{  
   "desc": true,  
   "filters": [  
       {  
           "filterKey": "avgViews1Y",  
           "op": "<",  
           "value": 100000  
       }  
   ],  
   "maxResults": 5,  
   "offset": 0,  
   "sortBy": "subscribers"  
}

{  
   "data": [  
       "UCpEhnqL0y41EpW2TvWAHD7Q",  
       "UC6-F5tO8uklgE9Zy8IvbdFw",  
       "UCppHT7SZKKvar4Oc9J4oljQ",  
       "UC55IWqFLDH1Xp7iu1_xknRA",  
       "UCrnQFuUabBHaw-BRhPo8xEA"  
   ],  
   "quotaUsed": 1,  
   "quotaUsedTotal": 212,  
   "remainingPlanCredit": 0,  
   "remainingPrepurchasedCredit": 99788,  
   "timestamp": 1750148520048,  
   "error": "",  
   "success": true  
}

Filtering by `avgViews1Y` within a range

Use the < and > operators in two avgViews1Y filterKeys to find YouTube creators with average views within a specified range for up to 800 videos uploaded in the past year. For example, the API request below returns five creators with average views between 10,000 and 100,000 in the last year and lists their YouTube IDs in descending order of subscribers.

Request example
Response example

curl --request POST \  
--url https: //dev.creatordb.app/v2/youtubeAdvancedSearch \
--header 'Accept: application/json' \  
--header 'Content-Type: application/json' \  
--header 'apiId: YOUR_API_KEY' \ 
--data '{  
"desc": true,  
"filters": [  
   {  
       "filterKey": "avgViews1Y",  
       "op": ">",  
       "value": 10000  
   },  
   {  
       "filterKey": "avgViews1Y",  
       "op": "<",  
       "value": 100000  
   }  
],  
"maxResults": 5,  
"offset": 0,  
"sortBy": "subscribers"  
}

{  
  "data": [  
      "UCpEhnqL0y41EpW2TvWAHD7Q",  
      "UC6-F5tO8uklgE9Zy8IvbdFw",  
      "UCppHT7SZKKvar4Oc9J4oljQ",  
      "UCaayLD9i5x4MmIoVZxXSv_g",  
      "UCffDXn7ycAzwL2LDlbyWOTw"  
  ],  
  "quotaUsed": 1,  
  "quotaUsedTotal": 213,  
  "remainingPlanCredit": 0,  
  "remainingPrepurchasedCredit": 99787,  
  "timestamp": 1750148731120,  
  "error": "",  
  "success": true  
}

Using country as a filter in YouTube advanced search

You can search for YouTube creators by their channel’s country with the ISO three-letter country code. For details, see Country Codes.

Filtering by `country` with a single value

Use the = operator to specify a single country value. For example, the API request below will return five YouTube creators in the U.S. and list them in descending followers order.

Request example
Response example

curl --request POST \ 
--url https: //dev.creatordb.app/v2/youtubeAdvancedSearch \  
--header 'Accept: application/json' \  
--header 'Content-Type: application/json' \  
--header 'apiId: YOUR_API_KEY' \  
--data '{  
"desc": true,  
"filters": [  
    {  
        "filterKey": "country",  
        "op": "=",  
        "value": "USA"  
    }  
],  
"maxResults": 5,  
"offset": 0,  
"sortBy": "subscribers"  
}

{  
   "data": [  
       "UCX6OQ3DkcsbYNE6H8uQQuVA",  
       "UCbCmjCuTUZos6Inko4u57UQ",  
       "UCvlE5gTbOvjiolFlEm-c_Ow",  
       "UCk8GzjMOrta8yxDcKfylJYw",  
       "UCJplp5SjeGSdVdwsfb9Q7lQ"  
   ],  
   "quotaUsed": 1,  
   "quotaUsedTotal": 209,  
   "remainingPlanCredit": 0,  
   "remainingPrepurchasedCredit": 99791,  
   "timestamp": 1750145795858,  
   "error": "",  
   "success": true  
}

Filtering by `country` with multiple values

Use the in operator to specify multiple country values. For example, the API request below will return five YouTube creators that are in the U.S. or the UK and list them in descending subscribers order.

Request example
Response example

curl --request POST \ 
--url https: //dev.creatordb.app/v2/youtubeAdvancedSearch \
--header 'Accept: application/json' \ 
--header 'Content-Type: application/json' \  
--header 'apiId: YOUR_API_KEY' \ 
--data '{  
   "desc": true,  
   "filters": [  
       {  
           "filterKey": "country",  
           "op": "in",  
           "value": [  
               "USA",  
               "GBR"  
           ]  
       }  
   ],  
   "maxResults": 5,  
   "offset": 0,  
   "sortBy": "subscribers"  
}

{  
   "data": [  
       "UCX6OQ3DkcsbYNE6H8uQQuVA",  
       "UCbCmjCuTUZos6Inko4u57UQ",  
       "UCvlE5gTbOvjiolFlEm-c_Ow",  
       "UCk8GzjMOrta8yxDcKfylJYw",  
       "UCJplp5SjeGSdVdwsfb9Q7lQ"  
   ],  
   "quotaUsed": 1,  
   "quotaUsedTotal": 210,  
   "remainingPlanCredit": 0,  
   "remainingPrepurchasedCredit": 99790,  
   "timestamp": 1750146498338,  
   "error": "",  
   "success": true  
}  

Using content as a filter in YouTube advanced search

CreatorDB provides two types of content categorization filters, topics and niches. Topics are a list of subjects compiled by CreatorDB’s proprietary system for categorizing a YouTube channel. Whereas niches are content keywords labeled by YouTube creators that are cleaned and aggregated by CreatorDB proprietary system to categorize the creator’s content type. You need the topics and niches IDs to look up a topic or niche name. To get a YouTube channel’s topics and niches IDs, call the Get the topic table API. For details, see the API Reference.

Filtering by `topic` with a single value

Use the = operator to find YouTube creators who match a certain topic. For example, the API request below finds five creators with the topic value id_roblox_Gaming and lists their YouTube IDs in descending order of subscribers.

Request example
Response example

curl --request POST \  
--url https: //dev.creatordb.app/v2/youtubeAdvancedSearch \  
--header 'Accept: application/json' \ 
--header 'Content-Type: application/json' \  
--header 'apiId: YOUR_API_KEY' \ 
--data '{  
   "desc": true,  
   "filters": [  
       {  
           "filterKey": "topic",  
           "op": "=",  
           "value": "id_roblox_Gaming"  
       }  
   ],  
   "maxResults": 5,  
   "offset": 0,  
   "sortBy": "subscribers"  
}

{  
   "data": [  
       "UCSf0s2ogUVYpJPuzW1zpAOg",  
       "UCS5Oz6CHmeoF7vSad0qqXfw",  
       "UCke6I9N4KfC968-yRcd5YRg",  
       "UCC-RHF_77zQdKcA75hr5oTQ",  
       "UCelMeixAOTs2OQAAi9wU8-g"  
   ],  
   "quotaUsed": 1,  
   "quotaUsedTotal": 214,  
   "remainingPlanCredit": 0,  
   "remainingPrepurchasedCredit": 99786,  
   "timestamp": 1750150708713,  
   "error": "",  
   "success": true  
}

Using the target audience as a filter in YouTube advanced search

You can search for YouTube creators based on their target audience metrics. The following are available demographic filters:

demographic.mainCountry
demographic.avgAge
demographic.mainCountryRatio
demographic.genderFemaleRatio
demographic.genderMaleRatio
For details, see Configuring Filters for YouTube Advanced Search.

You will be charged 1 API credit for every 10 filter objects included in a single request. For example, 1–10 filters = 1 credit, 11–20 filters = 2 credits, and so on.

Filtering by audience country and female viewer ratio with single values

You can combine multiple demographic filters to limit the YouTube creator’s search scope to a specific target audience. For example, the API request below shows how you can find creators whose main audience is from the U.S. and has less than 40 percent of female viewers. The request below will return five YouTube creators that meet the filter conditions and list them in descending order of subscribers.

Request example
Response example

curl --request POST \  
--url https: //dev.creatordb.app/v2/youtubeAdvancedSearch \  
--header 'Accept: application/json' \  
--header 'Content-Type: application/json' \  
--header 'apiId: YOUR_API_KEY' \  
--data '{  
   "desc": true,  
   "filters": [  
       {  
           "filterKey": "demographic.mainCountry",  
           "op": "=",  
           "value": "USA"  
       },  
       {  
           "filterKey": "demographic.genderFemaleRatio",  
           "op": "<",  
           "value": 0.4  
       }  
   ],  
   "maxResults": 5,  
   "offset": 0,  
   "sortBy": "subscribers"  
}

{  
   "data": [  
       "UCbCmjCuTUZos6Inko4u57UQ",  
       "UCvlE5gTbOvjiolFlEm-c_Ow",  
       "UCk8GzjMOrta8yxDcKfylJYw",  
       "UCJplp5SjeGSdVdwsfb9Q7lQ",  
       "UC-lHJZR3Gqxm24_Vd_AJ5Yw"  
   ],  
   "quotaUsed": 1,  
   "quotaUsedTotal": 221,  
   "remainingPlanCredit": 0,  
   "remainingPrepurchasedCredit": 99779,  
   "timestamp": 1750153570274,  
   "error": "",  
   "success": true  
}

Filtering by audience country and female viewer ratio within a specific range

You can use multiple values to set a range or additional target audience search conditions. For example, the API request below shows how to find creators with audiences from multiple countries and a female viewer ratio within a specific range. The API request below will return five YouTube creators that have viewers from Argentina and Brazil, with between 10 percent to 40 percent female viewers. The creator’s YouTube IDs will be listed by the number of channel subscribers in descending order.

Request example
Response example

curl --request POST \ 
--url https: //dev.creatordb.app/v2/youtubeAdvancedSearch \ 
--header 'Accept: application/json' \  
--header 'Content-Type: application/json' \  
--header 'apiId: YOUR_API_KEY' \  
--data '{  
   "desc": true,  
   "filters": [  
       {  
           "filterKey": "demographic.mainCountry",  
           "op": "in",  
           "value": [  
               "BRA",  
               "ARE"  
           ]  
       },  
       {  
           "filterKey": "demographic.genderFemaleRatio",  
           "op": ">",  
           "value": 0.1  
       },  
       {  
           "filterKey": "demographic.genderFemaleRatio",  
           "op": "<",  
           "value": 0.4  
       }  
   ],  
   "maxResults": 5,  
   "offset": 0,  
   "sortBy": "subscribers"  
}

{  
   "data": [  
       "UCVNouUw3d3l5JYVCxhAQXKA",  
       "UC_gV70G_Y51LTa3qhu8KiEA",  
       "UCmBA_wu8xGg1OfOkfW13Q0Q",  
       "UCKe6w0exI94U-RzqAyoY1VA",  
       "UCV306eHqgo0LvBf3Mh36AHg"  
   ],  
   "quotaUsed": 1,  
   "quotaUsedTotal": 225,  
   "remainingPlanCredit": 0,  
   "remainingPrepurchasedCredit": 99775,  
   "timestamp": 1750154277784,  
   "error": "",  
   "success": true  
}  

Using filters in Instagram advanced search

Search for Instagram creators using various filter options.

Using followers as a filter

Filter Instagram creators by follower count.

Using average comments as a filter

Filter Instagram creators by average comments.

Using the category as a filter

Filter Instagram creators by categories.

Using multiple filters

Use multiple filters to search for specific Instagram creators.

Configuring filters for Instagram advanced search

This page lists the available filterKey options for the Instagram Advanced Search API, including data types, usage examples, and notes on sorting.

Available `filterKey` and `sortBy` options

The table below lists the available filterKey options you can use with the Instagram Advanced Search API. Each entry includes the expected data type, an example value, and indicates whether the field supports sorting.

Column definitions

Supports sorting

Indicates whether this field can also be used as a sortBy parameter. When the field is checkmarked, it supports sorting search results by that parameter in ascending or descending order.

The sorting behavior depends on the data type— for example, strings are sorted alphabetically.

Available Filter	Type	Example	Definition	Supports sorting
avgComments	`number`	106.6206897	The average comments per post (excluding older pinned posts).	✅
avgLikes	`number`	14324.24138	The average likes per post (excluding older pinned posts).	✅
category	`string`	Art	This field represents the account category defined by creators with professional accounts. See over 1,000 of the most commonly used categories in the Instagram Categories list. Fuzzy search is not supported.	✅
country	`string` or `string [ ]`	TWN or [country1, country2, …]	The country associated with the Instagram creator, represented in ISO 3166-1 alpha-3 format. For details, see Country Codes.	✅
engageRate	`number`	0.02404943266	The average engagement rate per post (excluding older pinned posts). Engagement rate is calculated as (likes + comments) / followers.	✅
followers	`number`	600050	The number of users who follow the Instagram creator.	✅
following	`number`	1181	The number of users the Instagram creator follows.	✅
gRateAvgComments	`number`	0.1667924528	The 30-day growth rate of `avgComments`, which represents the average number of comments per post, calculated from the creator’s most recent 20 posts (excluding older pinned posts).	✅
gRateAvgLikes	`number`	0.1457433487	The 30-day growth rate of `avgLikes`, which represents the average number of likes per post, calculated from the creator’s most recent 20 posts (excluding older pinned posts).	✅
gRateEngageRate	`number`	0.1346653267	The 30-day growth rate of `engageRate`, which represents the average engagement rate per post, calculated from the creator’s most recent 20 posts (excluding older pinned posts).	✅
gRateFollowers	`number`	0.009897857344	The 30-day growth rate of followers, which represents the number of users who follow the Instagram creator.	✅
hashtags	`string`	#swimsuit	The set of unique hashtags used across the creator’s posts.	⬜
instagramName	`string`	愛莉莎莎 Alisasa 🐨	The display name set by the Instagram creator.	✅
isVerified	`boolean`	TRUE	Indicates whether the creator’s Instagram account is verified. Returns `TRUE` when the account is verified. Otherwise, it returns `FALSE`.	⬜
lang	`string` or `string []`	zht or [lang1, lang2, …]	The main language used in the creator’s posts, represented in ISO 639-3 format. For details, see Language Codes.	✅
lastPublishTime	`number`	1748681542000	The upload time of the most recent post among the creator’s most recent 20 posts, represented as a Unix timestamp in milliseconds.	✅
nicheIds	`string`	`id_india_All` or `india`	Represents unified content themes identified by CreatorDB’s AI model, which analyzes and groups keywords, hashtags, and tags used by creators. To get valid niche values for filters, call the Get Topic and Niche Table API.	⬜
posts	`number`	1603	The total number of posts uploaded by the Instagram creator.	✅

Using followers as a filter in Instagram advanced search

The examples below demonstrate some common Instagram followers filter configurations.

By default, CreatorDB will list search results in descending instagramId order.

Filtering by `followers` with a minimum value

By specifying greater than (> ) as the operation value, you can search for Instagram creators with a minimum number of followers. The following example will search the CreatorDB database for two creators with at least 1,000 followers and list their Instagram IDs by descending followers.

Request example
Response example

curl --request POST \ 
--url https: //dev.creatordb.app/v2/instagramAdvancedSearch \ 
--header 'Accept: application/json' \  
--header 'Content-Type: application/json' \ 
--header 'apiId: YOUR_API_KEY' \  
--data '{  
"desc": true,  
"filters": [  
   {  
       "filterKey": "followers",  
       "op": ">",  
       "value": 1000  
   }  
],  
"maxResults": 2,  
"offset": 0,  
"sortBy": "followers"  
}

{  
   "data": [  
       "instagram",  
       "cristiano"  
   ],  
   "quotaUsed": 1,  
   "quotaUsedTotal": 226,  
   "remainingPlanCredit": 0,  
   "remainingPrepurchasedCredit": 99774,  
   "timestamp": 1750407553467,  
   "error": "",  
   "success": true  
}

Filtering by `followers` with a maximum value

By specifying less than (< ) as the operation value, you can search for Instagram creators with a maximum number of followers. The following example will search the CreatorDB database for two creators with fewer than 5,000 followers and list their Instagram ID by descending followers.

Request example
Response example

curl --request POST \ 
--url https: //dev.creatordb.app/v2/instagramAdvancedSearch \ 
--header 'Accept: application/json' \  
--header 'Content-Type: application/json' \  
--header 'apiId: YOUR_API_KEY' \  
--data '{  
   "desc": true,  
   "filters": [  
       {  
           "filterKey": "followers",  
           "op": "<",  
           "value": 5000  
       }  
   ],  
   "maxResults": 2,  
   "offset": 0,  
   "sortBy": "followers"  
}

{  
"data": [  
    "nakajimacha",  
    "skarlow_"  
],  
"quotaUsed": 1,  
"quotaUsedTotal": 227,  
"remainingPlanCredit": 0,  
"remainingPrepurchasedCredit": 99773,  
"timestamp": 1750408213703,  
"error": "",  
"success": true  
}

Filtering by `followers` within a range

You can specify the range in advanced search filters by using the filter operations greater than (>) and less than (<). For example, the request example below will return two Instagram IDs with 1,000 to 5,000 followers and list the results by descending followers order.

Request example
Response example

curl --request POST \
--url https: //dev.creatordb.app/v2/instagramAdvancedSearch \ 
--header 'Accept: application/json' \ 
--header 'Content-Type: application/json' \
--header 'apiId: YOUR_API_KEY' \ 
--data '{  
   "desc": true,  
   "filters": [  
       {  
           "filterKey": "followers",   
           "op": ">",  
           "value": 1000  
       },  
       {  
           "filterKey": "followers",   
           "op": "<",  
           "value": 5000  
       }  
   ],  
   "maxResults": 2,  
   "offset": 0,  
   "sortBy": "followers"  
}

{  
   "data": [  
       "aarumdwi",  
       "heidari_abulfazl"  
   ],  
   "quotaUsed": 1,  
   "quotaUsedTotal": 228,  
   "remainingPlanCredit": 0,  
   "remainingPrepurchasedCredit": 99772,  
   "timestamp": 1750408904752,  
   "error": "",  
   "success": true  
}  

Using average comments as a filter in Instagram advanced search

CreatorDB provides various metrics to evaluate a creator’s average Instagram performance—such as avgComments, avgLikes, and engageRate—which can be used as filters in advanced search. The example below demonstrates how to apply a filter using avgComments.

Filtering by `avgComments` with a minimum value

By specifying greater than (> ) as the operation value, you can search for Instagram creators with a minimum number of average comments. The following example will search the CreatorDB database for two creators with average comments exceeding 1,000 per post and list their Instagram IDs by descending followers.

Request example
Response example

curl --request POST \ 
--url https: //dev.creatordb.app/v2/instagramAdvancedSearch \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \  
--header 'apiId: YOUR_API_KEY' \  
--data '{  
  "desc": true,  
  "filters": [  
      {  
          "filterKey": "avgComments",  
          "op": ">",  
          "value": 1000  
      }  
  ],  
  "maxResults": 2,  
  "offset": 0,  
  "sortBy": "followers"  
}

{  
   "data": [  
       "instagram",  
       "cristiano"  
   ],  
   "quotaUsed": 1,  
   "quotaUsedTotal": 229,  
   "remainingPlanCredit": 0,  
   "remainingPrepurchasedCredit": 99771,  
   "timestamp": 1750411000927,  
   "error": "",  
   "success": true  
}

Filtering by `avgComments` with a maximum value

By specifying less than (< ) as the operation value, you can search for Instagram creators with a maximum number of average comments. The following example will search the CreatorDB database for two creators with average comments of less than 10,000 per post, and list their Instagram IDs by descending order of followers.

Request example
Response example

curl --request POST \
--url https: //dev.creatordb.app/v2/instagramAdvancedSearch \  
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \  
--header 'apiId: YOUR_API_KEY' \  
--data '{  
   "desc": true,  
   "filters": [  
       {  
           "filterKey": "avgComments",  
           "op": "\<",  
           "value": 10000  
       }  
   ],  
   "maxResults": 2,  
   "offset": 0,  
   "sortBy": "followers"  
}

{  
"data": [  
    "instagram",  
    "selenagomez"  
],  
"quotaUsed": 1,  
"quotaUsedTotal": 231,  
"remainingPlanCredit": 0,  
"remainingPrepurchasedCredit": 99769,  
"timestamp": 1750658085826,  
"error": "",  
"success": true  
}

Filtering by `avgComments` within a range

Use the < and > operators to find Instagram creators with average comments within a specified range. For example, the API request below returns two Instagram creators with average comments between 1,000 to 10,000 per post and lists them by descending order of followers.

Request example
Response example

curl --request POST \  
--url https: //dev.creatordb.app/v2/instagramAdvancedSearch\  
--header 'Accept: application/json' \  
--header 'Content-Type: application/json' \  
--header 'apiId: YOUR_API_KEY' \
--data '{  
   "desc": true,  
   "filters": [  
       {  
           "filterKey": "avgComments",  
           "op": ">",  
           "value": 1000  
       },  
       {  
           "filterKey": "avgComments",  
           "op": "<",  
           "value": 10000  
       }  
   ],  
   "maxResults": 2,  
   "offset": 0,  
   "sortBy": "followers"  
}

{  
   "data": [  
       "kimkardashian",  
       "justinbieber"  
    ],  
   "quotaUsed": 1,  
   "quotaUsedTotal": 235,  
   "remainingPlanCredit": 0,  
   "remainingPrepurchasedCredit": 99765,  
   "timestamp": 1750658414301,  
   "error": "",  
   "success": true  
}

Using the category as a filter in Instagram advanced search

You can use Instagram business categories as a filter to find creators. Instagram defines these categories. For details, see Instagram Categories.

Filtering by `category` with a single value

Use the = operator to specify a single category value. For example, the API request below will return two Instagram creators in the artist category and list them in descending followers order.

Request example
Response example

curl --request POST \ 
--url https: //dev.creatordb.app/v2/instagramAdvancedSearch \  
--header 'Accept: application/json' \  
--header 'Content-Type: application/json' \ 
--header 'apiId: YOUR_API_KEY' \
--data '{  
   "desc": true,  
   "filters": [  
       {  
           "filterKey": "category",  
           "op": "=",  
           "value": "Artist"  
       }  
   ],  
   "maxResults": 2,  
   "offset": 0,  
   "sortBy": "followers"  
}

{  
"data": [  
   "selenagomez",  
   "jlo"  
],  
"quotaUsed": 1,  
"quotaUsedTotal": 237,  
"remainingPlanCredit": 0,  
"remainingPrepurchasedCredit": 99763,  
"timestamp": 1750661073342,  
"error": "",  
"success": true  
}

Filtering by `category` with multiple values

Use the in operator to specify multiple category values. For example, the API request below will return two Instagram creators in the artist and brand categories and list them in descending followers order.

Request example
Response example

curl --request POST \  
--url https: //dev.creatordb.app/v2/instagramAdvancedSearch \  
--header 'Accept: application/json' \  
--header 'Content-Type: application/json' \  
--header 'apiId: YOUR_API_KEY' \  
--data '{  
   "desc": true,  
   "filters": [  
       {  
           "filterKey": "category",  
           "op": "in",  
           "value": [  
               "Artist",  
               "Brand"  
           ]  
       }  
   ],  
   "maxResults": 2,  
   "offset": 0,  
   "sortBy": "followers"  
}

{  
   "data": [  
       "selenagomez",  
       "jlo"  
   ],  
   "quotaUsed": 1,  
   "quotaUsedTotal": 238,  
   "remainingPlanCredit": 0,  
   "remainingPrepurchasedCredit": 99762,  
   "timestamp": 1750661349091,  
   "error": "",  
   "success": true  
}

Using multiple filters in Instagram advanced search

You can use multiple filters to narrow Instagram advanced search results.

You will be charged 1 API credit for every 10 filter objects included in a single request. For example, 1–10 filters = 1 credit, 11–20 filters = 2 credits, and so on.

Filtering by average likes and engagement rate with single values

To apply multiple filters in your Instagram Advanced Search request, provide the corresponding filter parameters in the request body. For example, the API request below will return two Instagram creators that have more than 100,000 average likes and a 10% engagement rate, calculated from the most recent 20 posts.

Request example
Response example

curl --request POST \  
--url https: //dev.creatordb.app/v2/instagramAdvancedSearch \ 
--header 'Accept: application/json' \  
--header 'Content-Type: application/json' \ 
--header 'apiId: YOUR_API_KEY' \  
--data '{  
   "desc": true,  
   "filters": [  
       {  
           "filterKey": "avgLikes",  
           "op": ">",  
           "value": 100000  
       },  
       {  
           "filterKey": "engageRate",  
           "op": ">",  
           "value": 0.1  
       }  
   ],  
   "maxResults": 2,  
   "offset": 0,  
   "sortBy": "followers"  
}

{  
   "data": [  
       "ishowspeed",  
       "6ix9ine"  
   ],  
   "quotaUsed": 1,  
   "quotaUsedTotal": 240,  
   "remainingPlanCredit": 0,  
   "remainingPrepurchasedCredit": 99760,  
   "timestamp": 1750662962061,  
   "error": "",  
   "success": true  
}  

Using filters in TikTok advanced search

Search for TikTok creators using various filter options.

Using followers as a filter

Filter TikTok creators by follower count.

Using average plays as a filter

Filter TikTok creators by average plays.

Using the language as a filter

Filter TikTok creators by language.

Using multiple filters

Use multiple filters to find specific TikTok creators.

Configuring filters for TikTok advanced search

This page lists the available filterKey options for the TikTok Advanced Search API, including data types, usage examples, and notes on sorting.

Available `filterKey` and `sortBy` options

The table below lists the available filterKey options you can use with the TikTok Advanced Search API. Each entry includes the expected data type, an example value, and indicates whether the field supports sorting.

Column definitions

Supports sorting

Indicates whether this field can also be used as a sortBy parameter. When the field is checkmarked, it supports sorting results by that parameter in ascending or descending order.

The sorting behavior depends on the data type— for example, strings are sorted alphabetically.

Available Filter	Type	Example	Definition	Supports sorting
avgComments	`number`	17	The average comments per post (rounded to the nearest whole number).	✅
avgHearts	`number`	3176	The average hearts per post (rounded to the nearest whole number).	✅
avgLength	`number`	13	The average video length (in seconds) per post, rounded to the nearest whole number.	✅
avgPlays	`number`	22976	The average plays per post, rounded to the nearest whole number.	✅
avgShares	`number`	13	The average shares per post, rounded to the nearest whole number.	✅
country	`string` or `string [ ]`	GBR or [country1, country2, …]	The country associated with the TikTok creator, represented in ISO 3166-1 alpha-3 format. For details, see Country Codes.	✅
engageRate	`number`	0.1395629241	The average engagement rate per post. Engagement rate is calculated as [ (likes + shares+ comments) / plays].	✅
followers	`number`	38200	The number of users who follow the TikTok creator.	✅
following	`number`	4905	The number of users the TikTok creator follows.	✅
gRateAvgComments	`number`	0	The 30-day growth rate of `avgComments`, which represents the average comments per post.	✅
gRateAvgHearts	`number`	0	The 30-day growth rate of `avgHearts`, which represents the average hearts per post.	✅
gRateAvgPlays	`number`	0.0002176657525	The 30-day growth rate of `avgPlays`, which represents the average plays per post.	✅
gRateAvgShares	`number`	0	The 30-day growth rate of `avgShares`, which represents the average shares per post.	✅
gRateEngageRate	`number`	-0.0002029265616	The 30-day growth rate of `avgEngageRate`, which represents the average engagement rate per post.	✅
gRateFollowers	`number`	-0.002610966057	The 30-day growth rate of followers, which represents the total number of users following the TikTok creator.	✅
gRateHearts	`number`	0	The 30-day growth rate of hearts, which represents the total number of likes the creator has received on posts since their account’s creation.	✅
hashtags	`string`	#foryoupage	A list of unique hashtags collected from the creator’s posts.	⬜
hearts	`number`	711100	The total number of likes the creator has received on posts since account creation	✅
isVerified	`boolean`	FALSE	Indicates whether the creator’s TikTok account is verified. Returns `TRUE` when the TikTok account is verified. Otherwise, it returns `FALSE`.	⬜
lang	`string` or `string [ ]`	eng or [lang1, lang2, …]	The main language used in the creator’s posts, represented in ISO 639-3 format. For details, see Language Codes.	✅
tiktokName	`string`	ajdbqvlq5dd	The display name set by the TikTok creator	✅
videos	`number`	304	The total number of videos uploaded by the TikTok creator.	✅

Using followers as a filter in TikTok advanced search

The examples below demonstrate some common TikTok followers filter configurations.

By default, CreatorDB will list search results by tiktokId in descending order.

Filtering by `followers` with a minimum value

By specifying greater than (> ) as the operation value, you can search for TikTok creators with a minimum number of followers. The following example will search the CreatorDB database for three creators with at least 1,000 followers and list their TikTok IDs in descending followers order.

Request example
Response example

curl --request POST \ 
--url https: //dev.creatordb.app/v2/tiktokAdvancedSearch \  
--header 'Accept: application/json' \  
--header 'Content-Type: application/json' \  
--header 'apiId: YOUR_API_KEY' \  
--data '{  
   "desc": true,  
   "filters": [  
       {  
           "filterKey": "followers",  
           "op": ">",  
           "value": 1000  
       }  
   ],  
   "maxResults": 3,  
   "offset": 0,  
   "sortBy": "followers"  
}

{  
   "data": [  
       "khaby.lame",  
       "charlidamelio",  
       "mrbeast"  
   ],  
   "quotaUsed": 1,  
   "quotaUsedTotal": 241,  
   "remainingPlanCredit": 0,  
   "remainingPrepurchasedCredit": 99759,  
   "timestamp": 1750732453635,  
   "error": "",  
   "success": true  
}

Filtering by `followers` with a maximum value

By specifying less than (< ) as the operation value, you can search for TikTok creators with a maximum number of followers. The following example will search the CreatorDB database for three creators with fewer than 10,000 followers and list their TikTok IDs in descending followers order.

Request example
Response example

curl --request POST \ 
--url https: //dev.creatordb.app/v2/tiktokAdvancedSearch \  
--header 'Accept: application/json' \  
--header 'Content-Type: application/json' \  
--header 'apiId: YOUR_API_KEY' \
--data '{  
   "desc": true,  
   "filters": [  
       {  
           "filterKey": "followers",  
           "op": "<",  
           "value": 10000  
       }  
   ],  
   "maxResults": 3,  
   "offset": 0,  
   "sortBy": "followers"  
}

{  
   "data": [  
       "ellie2000_",  
       "urgoddess101",  
       "astiind.ah"  
   ],  
   "quotaUsed": 1,  
   "quotaUsedTotal": 242,  
   "remainingPlanCredit": 0,  
   "remainingPrepurchasedCredit": 99758,  
   "timestamp": 1750732611028,  
   "error": "",  
   "success": true  
}

Filtering by `followers` within a range

You can specify the range in advanced search filters by using the filter operations greater than (>) and less than (<). For example, the request example below will return three TikTok IDs with 1,000 to 10,000 followers and list the results by descending followers order.

Request example

curl --request POST \  
--url https: //dev.creatordb.app/v2/tiktokAdvancedSearch \ 
--header 'Accept: application/json' \  
--header 'Content-Type: application/json' \  
--header 'apiId: YOUR_API_KEY' \  
--data '{  
   "desc": true,  
   "filters": [  
       {  
           "filterKey": "followers",  
           "op": ">",  
           "value": 1000  
       },  
       {  
           "filterKey": "followers",  
           "op": "<",  
           "value": 10000  
       }  
   ],  
   "maxResults": 3,  
   "offset": 0,  
   "sortBy": "followers"  
}
</Tab>
<Tab title="Response example">
```json
{  
   "data": [  
       "superheroblvck",  
       "punto_noticiaswowtv",  
       "al3jandropv"  
   ],  
   "quotaUsed": 1,  
   "quotaUsedTotal": 243,  
   "remainingPlanCredit": 0,  
   "remainingPrepurchasedCredit": 99757,  
   "timestamp": 1750734593945,  
   "error": "",  
   "success": true  
}  

Using average plays as a filter in TikTok advanced search

CreatorDB provides the following TikTok average metric filterKeys: avgComments, avgHearts, avgLength, avgPlays, avgShares, engageRate. The examples below demonstrate how to use average plays (avgPlays) as a filter to find TikTok creators.

Filtering by `avgPlays` with a minimum value

By specifying greater than (>) as the operation value, you can search for TikTok creators with a minimum number of average plays. The following example will search the CreatorDB database for three creators with average plays exceeding 1,000 per video and list their TikTok IDs by descending followers.

Request example
Response example

curl --request POST \  
--url https: //dev.creatordb.app/v2/tiktokAdvancedSearch \  
--header 'Accept: application/json' \  
--header 'Content-Type: application/json' \  
--header 'apiId: YOUR_API_KEY' \
--data '{  
   "desc": true,  
   "filters": [  
       {  
           "filterKey": "avgPlays",  
           "op": ">",  
           "value": 1000  
       }  
   ],  
   "maxResults": 3,  
   "offset": 0,  
   "sortBy": "followers"  
}

{  
   "data": [  
       "khaby.lame",  
       "charlidamelio",  
       "mrbeast"  
   ],  
   "quotaUsed": 1,  
   "quotaUsedTotal": 244,  
   "remainingPlanCredit": 0,  
   "remainingPrepurchasedCredit": 99756,  
   "timestamp": 1750736152711,  
   "error": "",  
   "success": true  
}

Filtering by `avgPlays` with a maximum value

By specifying less than (< ) as the operation value, you can search for TikTok creators with a maximum number of average plays. The following example will search the CreatorDB database for three creators with average plays of less than 10,000 per post, and list their TikTok IDs by descending order of followers.

Request example
Response example

curl --request POST \  
--url https: //dev.creatordb.app/v2/tiktokAdvancedSearch \  
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \ 
--header 'apiId: YOUR_API_KEY' \
--data '{  
   "desc": true,  
   "filters": [  
       {  
           "filterKey": "avgPlays",  
           "op": "\<",  
           "value": 10000  
       }  
   ],  
   "maxResults": 3,  
   "offset": 0,  
   "sortBy": "followers"  
}

{  
   "data": [  
       "zachking",  
       "hytalosantosoficial",  
       "ecn1a"  
   ],  
   "quotaUsed": 1,  
   "quotaUsedTotal": 245,  
   "remainingPlanCredit": 0,  
   "remainingPrepurchasedCredit": 99755,  
   "timestamp": 1750736242390,  
   "error": "",  
   "success": true  
}

Filtering by `avgPlays` within a range

Use the < and > operators to find TikTok creators with average plays within a specified range. For example, the API request below returns three TikTok creators with average plays between 1,000 to 10,000 per post and lists them by descending order of followers.

Request example
Response example

curl --request POST \
--url https: //dev.creatordb.app/v2/tiktokAdvancedSearch \ 
--header 'Accept: application/json' \  
--header 'Content-Type: application/json' \  
--header 'apiId: YOUR_API_KEY' \
--data '{  
   "desc": true,  
   "filters": [  
       {  
           "filterKey": "avgPlays",  
           "op": ">",  
           "value": 1000  
       },  
       {  
           "filterKey": "avgPlays",  
           "op": "\<",  
           "value": 10000  
       }  
   ],  
   "maxResults": 3,  
   "offset": 0,  
   "sortBy": "followers"  

{  
   "data": [  
       "thu_cung_333",  
       "prof.henryindraguna",  
       "berdievgabinii"  
   ],  
   "quotaUsed": 1,  
   "quotaUsedTotal": 246,  
   "remainingPlanCredit": 0,  
   "remainingPrepurchasedCredit": 99754,  
   "timestamp": 1750736449114,  
   "error": "",  
   "success": true  
}  

Using the language as a filter in the TikTok advanced search

CreatorDB provides language as a TikTok advanced search filter. You can specify ISO three-letter language codes as the value. For details, see Language Codes.

Filtering by `lang` with a single value

Use the = operator to specify a single language value. For example, the API request below will return three TikTok creators that use English and list them in descending followers order.

Request example
Response example

curl --request POST \  
--url https: //dev.creatordb.app/v2/tiktokAdvancedSearch \  
--header 'Accept: application/json' \  
--header 'Content-Type: application/json' \  
--header 'apiId: YOUR_API_KEY' \ 
--data '{  
   "desc": true,  
   "filters": [  
       {  
           "filterKey": "lang",  
           "op": "=",  
           "value": "eng"  
       }  
   ],  
   "maxResults": 3,  
   "offset": 0,  
   "sortBy": "followers"  
}

{  
   "data": [  
       "khaby.lame",  
       "mrbeast",  
       "bellapoarch"  
   ],  
   "quotaUsed": 1,  
   "quotaUsedTotal": 247,  
   "remainingPlanCredit": 0,  
   "remainingPrepurchasedCredit": 99753,  
   "timestamp": 1750737013865,  
   "error": "",  
   "success": true  
}

Filtering by `lang` with multiple values

Use the in operator to specify multiple language values. For example, the API request below will return three TikTok creators that use English and Mandarin Chinese and list them in descending followers order.

Request example
Response example

curl \--request POST \ 
--url https: //dev.creatordb.app/v2/tiktokAdvancedSearch \ 
--header 'Accept: application/json' \  
--header 'Content-Type: application/json' \ 
--header 'apiId: YOUR_API_KEY' \  
--data '{  
   "desc": true,  
   "filters": [  
       {  
           "filterKey": "lang",  
           "op": "in",  
           "value": [  
               "eng",  
               "cmn"  
           ]  
       }  
   ],  
   "maxResults": 3,  
   "offset": 0,  
   "sortBy": "followers"  
}

{  
   "data": [  
       "khaby.lame",  
       "mrbeast",  
       "bellapoarch"  
   ],  
   "quotaUsed": 1,  
   "quotaUsedTotal": 248,  
   "remainingPlanCredit": 0,  
   "remainingPrepurchasedCredit": 99752,  
   "timestamp": 1750737484568,  
   "error": "",  
   "success": true  
}  

Using multiple filters in TikTok advanced search

You can use multiple filters to narrow TikTok advanced search results.

You will be charged 1 API credit for every 10 filter objects included in a single request. For example, 1–10 filters = 1 credit, 11–20 filters = 2 credits, and so on.

Filtering by `engageRate`, `avgShares`, and `avgLength` with single values

To apply multiple filters in your TikTok Advanced Search request, provide the corresponding filter parameters in the request body. For example, the API request below will return three TikTok creators that meet the criteria of having more than 10% engagement rate, greater than 500 average shares, with videos shorter than 90 seconds.

Request example
Response example

curl --request POST \ 
--url https: //dev.creatordb.app/v2/tiktokAdvancedSearch \ 
--header 'Accept: application/json' \  
--header 'Content-Type: application/json' \  
--header 'apiId: YOUR_API_KEY' \  
--data '{  
  "desc": true,  
  "filters": [  
      {  
          "filterKey": "engageRate",  
          "op": ">",  
          "value": 0.1  
      },  
      {  
          "filterKey": "avgShares",  
          "op": ">",  
          "value": 500  
      },  
      {  
          "filterKey": "avgLength",  
          "op": "<",  
          "value": 90  
      }  
  ],  
  "maxResults": 3,  
  "offset": 0,  
  "sortBy": "followers"  
}

{  
   "data": [  
       "kimberly.loaiza",  
       "domelipa",  
       "bts_official_bighit"  
   ],  
   "quotaUsed": 1,  
   "quotaUsedTotal": 249,  
   "remainingPlanCredit": 0,  
   "remainingPrepurchasedCredit": 99751,  
   "timestamp": 1750744139183,  
   "error": "",  
   "success": true  
}  

About brands advanced search

Search for specific brands using various filter options.

Using brands advanced search filters

Search for specific brands using various filter options.

Using brand name as a filter

Filter brands by their name.

Using a brand's Instagram ID as a filter

Filter brands by Instagram ID.

Using multiple filters

Filter brands using multiple filters.

Overview

CreatorDB supports searching for brands that have sponsored YouTube or Instagram creators with predefined filters. When making the API call, you can specify which predefined filters you’d like to add to your search using the POST method. By default, search results are listed alphabetically by the brandName.

API call flow

Step 1

Use the Brand Advanced Search API to find brands that have sponsored creators on YouTube or Instagram, based on the specified filter conditions. You can filter brands by name, headquarters location, and Instagram ID.

Step 2

Use the brandId from calling the advanced search API to get detailed brand information and performance metrics of their sponsored creators on YouTube and Instagram.

You will be charged 1 API credit for every 10 filter objects included in a single request. For example, 1–10 filters = 1 credit, 11–20 filters = 2 credits, and so on.

Request body parameters

Name	Required	Type	Example	Description
offset	True	`number`	0	Specifies the number of records to skip before returning results. For example, if the offset is 5,001 and there are 10,000 search results, the returned data will skip the first 5,000 results.
maxResults	True	`number`	100	The maximum number of records to return. The maximum number of search results returned per call is 2,500. After the 2,500 result, you must specify the offset value to get the remaining results.
sortBy	False	`string`	country	The field to sort results by. For example, if the value is `country`, the returned brands will be sorted by the countries of their sponsored creators.
desc	True	`boolean`	true	Specifies whether the data returned should be sorted in descending order. When the value is `true`, it will return data in descending order. Otherwise, when `false`, the returned data will be in ascending order.
filters	True	`object[ ]`		An array of filter objects that includes: `filterKey`,`op`, and `value`.
└─ filterKey	True	`string`	country	The field on which to apply the filter.
└─ op	True	`string`	=	The comparison operator. Available values include `in`, `>`, `=`, `<`. Note that all string type filter values support the operation `in`.
└─ value	True	`string`/`string [ ]`	TWN	The data type depends on the `filterKey`. For more details, please see Configuring Filters for Brand Advanced Search

Configuring filters for brand advanced search

This page lists the available filterKey options for the Brand Advanced Search API, including the data types, examples, and notes on data sorting. You can use multiple filterKey to narrow your search and find the most relevant brands that have sponsored creators on YouTube or Instagram. By default, results are sorted by brand name (brandName filter) in descending order.

Available `filterKey` and `sortBy` options

The table below lists the available filterKey options with the Brand Advanced Search API. Each entry includes the expected data type, an example value, and indicates whether the field supports sorting.

Column definitions

Supports sorting

Indicates whether this field can also be used as a sortBy parameter. When the field is checkmarked, it supports sorting search results by that parameter in ascending or descending order.

The sorting behavior depends on the data type— for example, strings are sorted alphabetically.

Available Filter	Type	Example	Definition	Supports sorting
brandIgIds	`string`	acer	The brand’s Instagram ID. Only a single value is accepted per request.	⬜
brandName	`string` or `string [ ]`	Acer or [brandName1, brandName2,..]	The brand name.	✅
country	`string` or `string[ ]`	TWN or [country1, country2, …]	The country where the brand is headquartered, in ISO 3166-1 alpha-3 format. For details, see Country Codes.	✅
industries	`string`	Computer	The brand’s industry, only a single value is accepted per request.	⬜
ytMainCountry	`string`	TWN	The top country associated with creators sponsored by the brand, represented in ISO 3166-1 alpha-3 format. For details, see Country Codes.	✅
ytMainLanguage	`string`	eng	The top language associated with creators sponsored by the brand, represented in ISO 639-3 format. For details, see Language Codes.	✅

Using the brand name as a filter in the brand advanced search

The following examples demonstrate how to use a competitor’s brand name as a filter to retrieve the corresponding brandId to query detailed sponsorship performance reports across Instagram and YouTube. To retrieve valid brand names for the value parameter, please refer to the brandTable API.

By default, CreatorDB lists search results by the sponsoring brand brandName in descending alphabetical order.

Filtering by `brandName` using a single value

By specifying = (equal) as the operation value, you can search for MUSIA ONE’s brandId.

Request example
Response example

curl --request POST \  
--url https: //dev.creatordb.app/v2/brandAdvancedSearchV2 \ 
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \ 
--header 'apiId: YOUR_API_KEY' \
--data '{  
   "desc": true,  
   "filters": [  
       {  
           "filterKey": "brandName",  
           "op": "=",  
           "value": "MUSIA ONE"  
       }  
   ],  
   "maxResults": 1,  
   "offset": 0,  
   "sortBy": ""  
}

{  
   "data": [  
       {  
           "brandId": "musia.ai",  
           "name": "MUSIA ONE"  
       }  
   ],  
   "quotaUsed": 1,  
   "quotaUsedTotal": 298,  
   "remainingPlanCredit": 99978,  
   "remainingPrepurchasedCredit": 99447,  
   "timestamp": 1752738485903,  
   "error": "",  
   "success": true  
}

Filtering by `brandName` using multiple values

By specifying in as the operation value, you can search for multiple brands’ brandId. The following example will return two results sorted by the brand’s location.

Request example
Response example

curl --request POST \
--url https: //dev.creatordb.app/v2/brandAdvancedSearchV2 \  
--header 'Accept: application/json' \ 
--header 'Content-Type: application/json' \  
--header 'apiId: YOUR_API_KEY' \  
--data '{  
  "desc": true,  
  "filters": [  
      {  
          "filterKey": "companyName",  
          "op": "in",  
          "value": [  
              "Acer",  
              "Razer"  
          ]  
      }  
  ],  
  "maxResults": 2,  
  "offset": 0,  
  "sortBy": "country"  
}

{  
   "data": [  
       {  
           "brandId": "razer.com",  
           "name": "Razer"  
       },  
       {  
           "brandId": "acer.com",  
           "name": "Acer"  
       }  
   ],  
   "quotaUsed": 1,  
   "quotaUsedTotal": 299,  
   "remainingPlanCredit": 99977,  
   "remainingPrepurchasedCredit": 99447,  
   "timestamp": 1752739086184,  
   "error": "",  
   "success": true  
}  

Using the brand Instagram ID as a filter in the brand advanced search

You can search for a brand’s information and details by using its Instagram ID (brandIgIds). You can get the brand’s Instagram ID (brandIgIds) from its Instagram URL. For example, if the URL is https://www.instagram.com/acer/, then the brandIgIds value would be acer.

By default, CreatorDB lists search results by the sponsoring brand brandName in descending alphabetical order.

Filtering by `brandIgIds` using a single value

You can enter only one brandIgIds value per API request.

By using the equals operator (=), you can specify which brand data to retrieve from the CreatorDB database.

Request example
Response example

curl --request POST \
--url https: //dev.creatordb.app/v2/brandAdvancedSearchV2 \ 
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'apiId: YOUR_API_KEY' \  
--data '{  
   "desc": true,  
   "filters": [  
       {  
           "filterKey": "brandIgIds",  
           "op": "=",  
           "value": "acer"  
       }  
   ],  
   "maxResults": 1,  
   "offset": 0,  
   "sortBy": ""  
}

{  
   "data": [  
       {  
           "brandId": "acer.com",  
           "name": "Acer"  
       }  
   ],  
   "quotaUsed": 1,  
   "quotaUsedTotal": 303,  
   "remainingPlanCredit": 99973,  
   "remainingPrepurchasedCredit": 99447,  
   "timestamp": 1753154174226,  
   "error": "",  
   "success": true  
}

Using multiple filters in brand advanced search

You can use multiple filters to narrow brand search results.

By default, CreatorDB lists search results by the sponsoring brand brandName in descending alphabetical order.
You will be charged 1 API credit for every 10 filter objects included in a single request. For example, 1–10 filters = 1 credit, 11–20 filters = 2 credits, and so on.

Filtering by `country` and `industries` using a single value

To apply multiple filters in your Brand Advanced Search request, include the corresponding filter parameters in the request body. For example, the API request below returns 5 brands in the U.S. fashion industry.

Request example
Response example

curl --request POST \ 
--url https: //dev.creatordb.app/v2/brandAdvancedSearchV2 \  
--header 'Accept: application/json' \  
--header 'Content-Type: application/json' \  
--header 'apiId: YOUR_API_KEY' \
--data '{  
   "desc": true,  
   "filters": [  
       {  
           "filterKey": "country",  
           "op": "=",  
           "value": "USA"  
       },  
       {  
           "filterKey": "industries",  
           "op": "=",  
           "value": "Fashion"  
       }  
   ],  
   "maxResults": 5,  
   "offset": 0,  
   "sortBy": ""  
}

{  
   "data": [  
       {  
           "brandId": "swimsuitsforall.com",  
           "name": "swimsuitsforall"  
       },  
       {  
           "brandId": "italist.com",  
           "name": "italist"  
       },  
       {  
           "brandId": "gorjana.com",  
           "name": "gorjana"  
       },  
       {  
           "brandId": "gravitydefyer.com",  
           "name": "g.defy"  
       },  
       {  
           "brandId": "zotosprofessional.com",  
           "name": "Zotos Professional"  
       }  
   ],  
   "quotaUsed": 1,  
   "quotaUsedTotal": 301,  
   "remainingPlanCredit": 99975,  
   "remainingPrepurchasedCredit": 99447,  
   "timestamp": 1752742349269,  
   "error": "",  
   "success": true  
}

Using filters in YouTube advanced search

Using subscribers as a filter

Using average views as a filter

Using the country as a filter

Using content as a filter

Using the target audience as a filter

​Configuring filters for YouTube advanced search

​Available filterKey and sortBy options

​Column definitions

​Supports sorting

​Returned only in youtubeDetail API

​Using subscribers as a filter in YouTube advanced search

​Filtering subscribers with a minimum value

​Filtering subscribers with a maximum value

​Filtering subscribers within a range

​Using average views as a filter in YouTube advanced search

​Filtering by avgViews1Y with a minimum value

​Filtering by avgViews1Y with a maximum value

​Filtering by avgViews1Y within a range

​Using country as a filter in YouTube advanced search

​Filtering by country with a single value

​Filtering by country with multiple values

​Using content as a filter in YouTube advanced search

​Filtering by topic with a single value

​Using the target audience as a filter in YouTube advanced search

​Filtering by audience country and female viewer ratio with single values

​Filtering by audience country and female viewer ratio within a specific range

Using filters in Instagram advanced search

Using followers as a filter

Using average comments as a filter

Using the category as a filter

Using multiple filters

​Configuring filters for Instagram advanced search

​Available filterKey and sortBy options

​Column definitions

​Supports sorting

​Using followers as a filter in Instagram advanced search

​Filtering by followers with a minimum value

​Filtering by followers with a maximum value

​Filtering by followers within a range

​Using average comments as a filter in Instagram advanced search

​Filtering by avgComments with a minimum value

​Filtering by avgComments with a maximum value

​Filtering by avgComments within a range

​Using the category as a filter in Instagram advanced search

​Filtering by category with a single value

​Filtering by category with multiple values

​Using multiple filters in Instagram advanced search

​Filtering by average likes and engagement rate with single values

Using filters in TikTok advanced search

Using followers as a filter

Using average plays as a filter

Using the language as a filter

Using multiple filters

​Configuring filters for TikTok advanced search

​Available filterKey and sortBy options

​Column definitions

​Supports sorting

​Using followers as a filter in TikTok advanced search

​Filtering by followers with a minimum value

​Filtering by followers with a maximum value

​Filtering by followers within a range

​Using average plays as a filter in TikTok advanced search

​Filtering by avgPlays with a minimum value

​Filtering by avgPlays with a maximum value

​Filtering by avgPlays within a range

​Using the language as a filter in the TikTok advanced search

​Filtering by lang with a single value

​Filtering by lang with multiple values

​Using multiple filters in TikTok advanced search

​Filtering by engageRate, avgShares, and avgLength with single values

About brands advanced search

Using brands advanced search filters

Using brand name as a filter

Using a brand's Instagram ID as a filter

Using multiple filters

​Brand advanced search filters

​Overview

​API call flow

​Request body parameters

Configuring filters for YouTube advanced search

Available `filterKey` and `sortBy` options

Column definitions

Supports sorting

Returned only in youtubeDetail API

Using subscribers as a filter in YouTube advanced search

Filtering subscribers with a minimum value

Filtering subscribers with a maximum value

Filtering subscribers within a range

Using average views as a filter in YouTube advanced search

Filtering by `avgViews1Y` with a minimum value

Filtering by `avgViews1Y` with a maximum value

Filtering by `avgViews1Y` within a range

Using country as a filter in YouTube advanced search

Filtering by `country` with a single value

Filtering by `country` with multiple values

Using content as a filter in YouTube advanced search

Filtering by `topic` with a single value

Using the target audience as a filter in YouTube advanced search

Filtering by audience country and female viewer ratio with single values

Filtering by audience country and female viewer ratio within a specific range

Configuring filters for Instagram advanced search

Available `filterKey` and `sortBy` options

Column definitions

Supports sorting

Using followers as a filter in Instagram advanced search

Filtering by `followers` with a minimum value

Filtering by `followers` with a maximum value

Filtering by `followers` within a range

Using average comments as a filter in Instagram advanced search

Filtering by `avgComments` with a minimum value

Filtering by `avgComments` with a maximum value

Filtering by `avgComments` within a range

Using the category as a filter in Instagram advanced search

Filtering by `category` with a single value

Filtering by `category` with multiple values

Using multiple filters in Instagram advanced search

Filtering by average likes and engagement rate with single values

Configuring filters for TikTok advanced search

Available `filterKey` and `sortBy` options

Column definitions

Supports sorting

Using followers as a filter in TikTok advanced search

Filtering by `followers` with a minimum value

Filtering by `followers` with a maximum value

Filtering by `followers` within a range

Using average plays as a filter in TikTok advanced search

Filtering by `avgPlays` with a minimum value

Filtering by `avgPlays` with a maximum value

Filtering by `avgPlays` within a range

Using the language as a filter in the TikTok advanced search

Filtering by `lang` with a single value

Filtering by `lang` with multiple values

Using multiple filters in TikTok advanced search

Filtering by `engageRate`, `avgShares`, and `avgLength` with single values

Brand advanced search filters

Overview

API call flow

Request body parameters

Configuring filters for brand advanced search

Available `filterKey` and `sortBy` options

Column definitions

Supports sorting

Using the brand name as a filter in the brand advanced search

Filtering by `brandName` using a single value

Filtering by `brandName` using multiple values

Using the brand Instagram ID as a filter in the brand advanced search

Filtering by `brandIgIds` using a single value

Using multiple filters in brand advanced search

Filtering by `country` and `industries` using a single value