> ## Documentation Index > Fetch the complete documentation index at: https://docs.creatordb.app/llms.txt > Use this file to discover all available pages before exploring further. # Configuring Advanced Search Filters and Examples > Learn how to configure advanced search filters for YouTube, Instagram, TikTok, and brand searches Select a tab to view the specific filter configurations and examples for that particular platform or brand. Search for YouTube creators using various filter options. Filter YouTube creators by subscriber count. Filter YouTube creators by average views. Filter YouTube creators by country. Filter YouTube creators by content. 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](https://docs.creatordb.app/api-v2/country-code). | ✅ | ⬜ | | 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](https://docs.creatordb.app/api-v2/country-code). | ✅ | ✅ | | 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](https://docs.creatordb.app/api-v2/youtube-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](https://docs.creatordb.app/api-v2/language-code). | ✅ | ✅ | | 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](https://docs.creatordb.app/api-reference/topic/topic-and-niche-table). | ⬜ | ⬜ | | 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](https://docs.creatordb.app/api-reference/topic/topic-and-niche-table). | ⬜ | ⬜ | | 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. ```json theme={null} 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 } ] }' ``` ```json theme={null} { "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. ```json theme={null} 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 } ], } } ``` ```json theme={null} { "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. ```json theme={null} 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 } ] }' ``` ```json theme={null} { "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. ```json theme={null} 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" } ``` ```json theme={null} { "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. ```json theme={null} 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" } ``` ```json theme={null} { "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. ```json theme={null} 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" } ``` ```json theme={null} { "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](https://docs.creatordb.app/api-v2/country-code). ### 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. ```json theme={null} 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" } ``` ```json theme={null} { "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. ```json theme={null} 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" } ``` ```json theme={null} { "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](https://docs.creatordb.app/api-reference/topic/topic-and-niche-table). ### 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. ```json theme={null} 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" } ``` ```json theme={null} { "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](https://docs.creatordb.app/api-v2/configuring_advanced_search_filters#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. ```json theme={null} 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" } ``` ```json theme={null} { "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. ```json theme={null} 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" } ``` ```json theme={null} { "data": [ "UCVNouUw3d3l5JYVCxhAQXKA", "UC_gV70G_Y51LTa3qhu8KiEA", "UCmBA_wu8xGg1OfOkfW13Q0Q", "UCKe6w0exI94U-RzqAyoY1VA", "UCV306eHqgo0LvBf3Mh36AHg" ], "quotaUsed": 1, "quotaUsedTotal": 225, "remainingPlanCredit": 0, "remainingPrepurchasedCredit": 99775, "timestamp": 1750154277784, "error": "", "success": true } ``` Search for Instagram creators using various filter options. Filter Instagram creators by follower count. Filter Instagram creators by average comments. Filter Instagram creators by categories. 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](https://docs.creatordb.app/api-v2/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](https://docs.creatordb.app/api-v2/country-code). | ✅ | | 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](https://docs.creatordb.app/api-v2/language-code). | ✅ | | 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](https://docs.creatordb.app/api-reference/topic/topic-and-niche-table). | ⬜ | | 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. ```json theme={null} 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" } ``` ```json theme={null} { "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. ```json theme={null} 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" } ``` ```json theme={null} { "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. ```json theme={null} 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" } ``` ```json theme={null} { "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. ```json theme={null} 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" } ``` ```json theme={null} { "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. ```json theme={null} 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" } ``` ```json theme={null} { "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. ```json theme={null} 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" } ``` ```json theme={null} { "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](https://docs.creatordb.app/api-v2/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. ```json theme={null} 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" } ``` ```json theme={null} { "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. ```json theme={null} 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" } ``` ```json theme={null} { "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. ```json theme={null} 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" } ``` ```json theme={null} { "data": [ "ishowspeed", "6ix9ine" ], "quotaUsed": 1, "quotaUsedTotal": 240, "remainingPlanCredit": 0, "remainingPrepurchasedCredit": 99760, "timestamp": 1750662962061, "error": "", "success": true } ``` Search for TikTok creators using various filter options. Filter TikTok creators by follower count. Filter TikTok creators by average plays. Filter TikTok creators by language. 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](https://docs.creatordb.app/api-v2/country-code). | ✅ | | 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](https://docs.creatordb.app/api-v2/language-code). | ✅ | | 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. ```json theme={null} 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" } ``` ```json theme={null} { "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. ```json theme={null} 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" } ``` ```json theme={null} { "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. ````json theme={null} 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" } ```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. ```json theme={null} 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" } ``` ```json theme={null} { "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. ```json theme={null} 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" } ``` ```json theme={null} { "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. ```json theme={null} 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" ``` ```json theme={null} { "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](https://docs.creatordb.app/api-v2/language-code). ### 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. ```json theme={null} 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" } ``` ```json theme={null} { "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. ```json theme={null} 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" } ``` ```json theme={null} { "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. ```json theme={null} 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" } ``` ```json theme={null} { "data": [ "kimberly.loaiza", "domelipa", "bts_official_bighit" ], "quotaUsed": 1, "quotaUsedTotal": 249, "remainingPlanCredit": 0, "remainingPrepurchasedCredit": 99751, "timestamp": 1750744139183, "error": "", "success": true } ``` Search for specific brands using various filter options. Search for specific brands using various filter options. Filter brands by their name. Filter brands by Instagram ID. Filter brands using multiple filters. ## Brand advanced search 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 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. 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. Brand Advanced Search API work flow

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](https://docs.creatordb.app/api-v2/configuring_advanced_search_filters#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](https://docs.creatordb.app/api-v2/country-code). | ✅ | | 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](https://docs.creatordb.app/api-v2/country-code). | ✅ | | ytMainLanguage | `string` | eng | The top language associated with creators sponsored by the brand, represented in ISO 639-3 format. For details, see [Language Codes](https://docs.creatordb.app/api-v2/language-code). | ✅ | ## 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`. ```json theme={null} 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": "" } ``` ```json theme={null} { "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. ```json theme={null} 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" } ``` ```json theme={null} { "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/](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. ```json theme={null} 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": "" } ``` ```json theme={null} { "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. ```json theme={null} 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": "" } ``` ```json theme={null} { "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 } ```