- YouTube
- Instagram
- TikTok
Using custom filters in YouTube 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.
Configuring Custom YouTube Filter Search Criteria
Method:POST
Description: Search for YouTube creators based on custom filter criteria such as displayName, subscriber count, video performance, and more.Request Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| filters | object[] | Yes | An array of filter objects that includes: filterName, op, and value. |
└ filterName | string | Yes | The field to apply the filter on. |
└ op | string | Yes | The comparison operator. - String fields support: =, in• Number fields support: >, =, <• Boolean fields support: = |
└ value | stringnumberstring[]boolean | Yes | The value to match. Type must match the filterName type.For in operator, provide string[]. |
└ isFuzzySearch | boolean | No | Default false. When set to true, the filter will perform a fuzzy match. Only applicable for string-type fields. |
| desc | boolean | No | Default false (Ascending). Set true for Descending order. |
| sortBy | string | No | The field to sort results by. See table below for supported fields. |
| pageSize | number | Yes | Specifies the maximum number of results to return. Max 100. |
| offset | number | Yes | Indicates the number of records to skip before starting to return results. |
Available filterName & sortBy
| Filter Name | Type | Supported Operators | Can be SortBy | Description |
|---|---|---|---|---|
| displayName | String | =, in | ✅ Yes | The name of the YouTube channel. |
| uniqueId | String | =, in | ✅ Yes | The YouTube username/handle. Constraint: Must be 3-100 characters, allowing letters, numbers, dots, hyphens, and underscores. Can include optional @ prefix (e.g., mrbeast or @mrbeast). |
| mainCategory | String | =, in | ✅ Yes | The primary category of the channel’s content. |
| country | String | =, in | ✅ Yes | The country associated with the channel. Constraint: Must be in ISO 3166-1 alpha-3 format (e.g., TWN, USA). |
| mainLanguage | String | =, in | ✅ Yes | The main language of the channel’s videos. Constraint: Must be in ISO 639-3 format. |
| languages | String | =, in | ✅ Yes | All languages used in the channel’s videos. Constraint: Must be in ISO 639-3 format. |
| secondLanguage | String | =, in | ✅ Yes | The secondary language used in the channel’s videos. Constraint: Must be in ISO 639-3 format. |
| hashtags | String | =, in | ❌ No | Keywords/tags used in video descriptions or tags. |
| niches | String | =, in | ❌ No | Represents unified content theme identified by CreatorDB’s AI model. |
| topics | String | =, in | ❌ No | YouTube specific topics associated with the channel. |
| mainAudienceLocation | String | =, in | ✅ Yes | The country where the channel’s audience is most concentrated. Constraint: Must be in ISO 3166-1 alpha-3 format. |
| mainAudienceAge | String | =, in | ✅ Yes | The primary age range of the channel’s audience. Allowed Values: "13-17", "18-24", "25-34", "35-44", "45-54", "55-64", "65+". |
| mainAudienceGender | String | =, in | ❌ No | The dominant gender group among the channel’s audience. Allowed Values: "male", "female". |
| totalSubscribers | Number | >, =, < | ✅ Yes | The total number of subscribers. |
| totalContents | Number | >, =, < | ✅ Yes | The total number of videos uploaded by the creator. |
| totalViews | Number | >, =, < | ✅ Yes | The total number of views across all videos. |
| lastPublishTime | Number | >, =, < | ✅ Yes | The timestamp of the most recent video upload (Unix timestamp in milliseconds). |
| subscriberGrowthIn30d | Number | >, =, < | ✅ Yes | The growth rate of subscribers in the past 30 days. |
| avgRecentVideosLikes | Number | >, =, < | ✅ Yes | Average likes per video (based on recent long-form videos). |
| avgVideosLikesAll | Number | >, =, < | ✅ Yes | Average likes per video (based on all-time long-form videos). |
| medianRecentVideosLikes | Number | >, =, < | ✅ Yes | Median likes per video (based on recent long-form videos). |
| medianVideosLikesAll | Number | >, =, < | ✅ Yes | Median likes per video (based on all-time long-form videos). |
| avgRecentVideosComments | Number | >, =, < | ✅ Yes | Average comments per video (based on recent long-form videos). |
| avgVideosCommentsAll | Number | >, =, < | ✅ Yes | Average comments per video (based on all-time long-form videos). |
| avgRecentVideosViews | Number | >, =, < | ✅ Yes | Average views per video (based on recent long-form videos). |
| avgVideosViewsAll | Number | >, =, < | ✅ Yes | Average views per video (based on all-time long-form videos). |
| medianRecentVideosViews | Number | >, =, < | ✅ Yes | Median views per video (based on recent long-form videos). |
| medianVideosViewsAll | Number | >, =, < | ✅ Yes | Median views per video (based on all-time long-form videos). |
| avgRecentVideosEngagementRate | Number | >, =, < | ✅ Yes | Average engagement rate for recent long-form videos. Calculated as (likes + comments) / subscribers. |
| avgVideosEngagementRateAll | Number | >, =, < | ✅ Yes | Average engagement rate for all-time long-form videos. |
| avgRecentShortsViews | Number | >, =, < | ✅ Yes | Average views per short (based on recent shorts). |
| avgShortsViewsAll | Number | >, =, < | ✅ Yes | Average views per short (based on all-time shorts). |
| medianRecentShortsViews | Number | >, =, < | ✅ Yes | Median views per short (based on recent shorts). |
| medianShortsViewsAll | Number | >, =, < | ✅ Yes | Median views per short (based on all-time shorts). |
| avgRecentShortsLikes | Number | >, =, < | ✅ Yes | Average likes per short (based on recent shorts). |
| avgShortsLikesAll | Number | >, =, < | ✅ Yes | Average likes per short (based on all-time shorts). |
| medianRecentShortsLikes | Number | >, =, < | ✅ Yes | Median likes per short (based on recent shorts). |
| medianShortsLikesAll | Number | >, =, < | ✅ Yes | Median likes per short (based on all-time shorts). |
| avgRecentShortsComments | Number | >, =, < | ✅ Yes | Average comments per short (based on recent shorts). |
| avgShortsCommentsAll | Number | >, =, < | ✅ Yes | Average comments per short (based on all-time shorts). |
| avgRecentShortsEngagementRate | Number | >, =, < | ✅ Yes | Average engagement rate for recent shorts. Calculated as (likes + comments) / subscribers. |
| avgShortsEngagementRateAll | Number | >, =, < | ✅ Yes | Average engagement rate for all-time shorts. |
| avgRecentContentsViews | Number | >, =, < | ✅ Yes | Average views across all content types (Videos + Shorts) in recent posts. |
| avgRecentContentsLikes | Number | >, =, < | ✅ Yes | Average likes across all content types (Videos + Shorts) in recent posts. |
| avgRecentContentsComments | Number | >, =, < | ✅ Yes | Average comments across all content types (Videos + Shorts) in recent posts. |
| avgRecentContentsEngagementRate | Number | >, =, < | ✅ Yes | Average engagement rate across all content types in recent posts. |
| avgRecentContentsViewsGrowth | Number | >, =, < | ✅ Yes | Growth rate of average views across all content types in recent posts. |
| avgRecentContentsLikesGrowth | Number | >, =, < | ✅ Yes | Growth rate of average likes across all content types in recent posts. |
| avgRecentContentsCommentsGrowth | Number | >, =, < | ✅ Yes | Growth rate of average comments across all content types in recent posts. |
| avgRecentContentsEngagementRateGrowth | Number | >, =, < | ✅ Yes | Growth rate of average engagement rate across all content types in recent posts. |
| avgRecentVideosViewsGrowth | Number | >, =, < | ✅ Yes | Growth rate of average views per long-form video in recent posts. |
| avgRecentVideosLikesGrowth | Number | >, =, < | ✅ Yes | Growth rate of average likes per long-form video in recent posts. |
| avgRecentVideosCommentsGrowth | Number | >, =, < | ✅ Yes | Growth rate of average comments per long-form video in recent posts. |
| avgRecentVideosEngagementRateGrowth | Number | >, =, < | ✅ Yes | Growth rate of average engagement rate per long-form video in recent posts. |
| avgRecentShortsViewsGrowth | Number | >, =, < | ✅ Yes | Growth rate of average views per short in recent posts. |
| avgRecentShortsLikesGrowth | Number | >, =, < | ✅ Yes | Growth rate of average likes per short in recent posts. |
| avgRecentShortsCommentsGrowth | Number | >, =, < | ✅ Yes | Growth rate of average comments per short in recent posts. |
| avgRecentShortsEngagementRateGrowth | Number | >, =, < | ✅ Yes | Growth rate of average engagement rate per short in recent posts. |
| subscriberCountPercentile | Number | >, =, < | ✅ Yes | Percentile ranking of subscriber count compared to all YouTube channels (0-100). |
| avgContentViewsPercentile | Number | >, =, < | ✅ Yes | Percentile ranking of average content views compared to all YouTube channels (0-100). |
| avgContentEngagementPercentile | Number | >, =, < | ✅ Yes | Percentile ranking of average content engagement compared to all YouTube channels (0-100). |
| subscriberCountPercentileGrowth | Number | >, =, < | ✅ Yes | Growth rate of subscriber count percentile ranking. |
| avgContentViewsPercentileGrowth | Number | >, =, < | ✅ Yes | Growth rate of average content views percentile ranking. |
| avgContentEngagementPercentileGrowth | Number | >, =, < | ✅ Yes | Growth rate of average content engagement percentile ranking. |
| platformScore | Number | >, =, < | ✅ Yes | CreatorDB proprietary platform score indicating overall influence. |
| joinedDate | Number | >, =, < | ✅ Yes | The timestamp when the channel was created (Unix timestamp in milliseconds). |
| contentsIn30Days | Number | >, =, < | ✅ Yes | Number of videos published in the last 30 days. |
| contentsIn90Days | Number | >, =, < | ✅ Yes | Number of videos published in the last 90 days. |
| audienceMaleRatio | Number | >, =, < | ✅ Yes | The percentage of male subscribers in the channel’s audience (0-100). |
| audienceFemaleRatio | Number | >, =, < | ✅ Yes | The percentage of female subscribers in the channel’s audience (0-100). |
| hasSponsors | Boolean | = | ❌ No | Indicates whether the channel has published sponsored content. |
Using Subscribers as a YouTube Filter Search Criteria
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 ten creators with at least 100,000 subscribers and list their YouTube ID in descending order.- Request example
- Response example
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 ten creators with less than 10,000 subscribers and list their YouTube ID in descending order.- Request example
- Response example
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 ten YouTube IDs with 10,000 to 100,000 subscribers.- Request example
- Response example
Using Average Views as a YouTube Filter Search Criteria
CreatorDB provides several average views filter options for YouTube videos and shorts.| Type | Filters |
|---|---|
| Videos and shorts combined | avgRecentContentsViews, avgRecentContentsViewsGrowth, avgContentViewsPercentile, avgContentViewsPercentileGrowth |
| Videos | avgVideosViewsAll, avgRecentVideosViews, avgRecentVideosViewsGrowth |
| Shorts | avgShortsViewsAll, avgRecentShortsViews, avgRecentShortsViewsGrowth |
Filtering by avgVideosViewsAll 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 ten creators with at least 10,000 average YouTube video views in the last year and lists their YouTube IDs in descending order of channel subscribers.- Request example
- Response example