CreatorDB calculates two types of engagement rates. The first type measures the audience’s engagement with a specific social media account or channel by using the number of followers or subscribers as the denominator. The second type is content (e.g. videos, shorts, posts, or reels) engagement rate, which measures the audience engagement with a piece of content by using the number of views as the denominator.The exception is Instagram image posts, which have no view count, and use followers as the denominator in the engagement rate calculation instead. As a result,
avgRecentImagesEngagementRate and avgRecentReelsEngagementRate are not directly comparable.- YouTube
- Instagram
- TikTok
- Sponsor
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.Important: Request Parameter Limits
- Filter Count: Unlimited number of filter objects. CreatorDB bills filters in blocks of 10 at 1 credit per block. A partial block counts as a full one (1–10 filters = 1 credit, 11–20 = 2, and so on).
- Array Value Limit: When using the
inoperator, the array can contain a maximum of 100 string values. - Page Size: The upper limit for
pageSizeis 100. - Fuzzy Search:
isFuzzySearch: trueis only available for String type fields.
Request parameters
| Name | Type | Required | Description |
|---|---|---|---|
| filters | object[] | Yes | Filter objects that include filterName, op, and value. |
└ filterName | string | Yes | The field to apply the filter on. |
└ op | string | Yes | The comparison operator. Accepted values include: in, >, =, <. - String fields accept: =, in. - Number fields accept: >, =, <. - Boolean fields accept: = |
└ value | stringnumberstring[]boolean | Yes | The filter value. Type depends on the filterName.For in operator, provide string[]. |
└ isFuzzySearch | boolean | No | Default false. When true, performs a fuzzy match for string type filterName. |
| desc | boolean | No | Sort order for results. true for descending, false for ascending order. Default is false. |
| sortBy | string | No | Field to sort creators by. See table below for supported fields. |
| pageSize | number | Yes | Number of results per page. Maximum: 100. |
| offset | number | Yes | Number of records to skip before returning results. Use this to paginate. |
Available filterName & sortBy
Note: Unless specified, YouTube videos refer to long-form videos and do not include reels or shorts in the table below.
| Filter Name | Type | Supported Operators | Can be SortBy | Description |
|---|---|---|---|---|
| Identity & Profile | ||||
| displayName | string or string[] | =, in | ✅ Yes | Channel display name. |
| uniqueId | string or string[] | =, in | ✅ Yes | The unique 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 or string[] | =, in | ✅ Yes | The primary category of the channel’s content. Based on the last 800 videos. |
| country | string or 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 or string[] | =, in | ✅ Yes | The primary language of the channel’s videos. Constraint: Must be in ISO 639-3 format. |
| languages | string or string[] | =, in | ✅ Yes | All languages used in contents. Constraint: Must be in ISO 639-3 format. |
| secondLanguage | string or string[] | =, in | ✅ Yes | The secondary language used in contents. Constraint: Must be in ISO 639-3 format. |
| hasMemberOnlyContents | boolean | = | ✅ Yes | Is true if the channel has member-only contents. |
| hasEmail | boolean | = | ✅ Yes | Is true if the channel has a business email. |
| Content & Discovery | ||||
| hashtags | string or string[] | =, in | ❌ No | Hashtags used in content and related statistics. |
| niches | string or string[] | =, in | ❌ No | Granular subcategories of content topics identified by CreatorDB’s AI model, which analyzes and groups keywords, hashtags, and tags used by creators. To get valid niche values for filterName, call /youtube/niches. |
| topics | string or string[] | =, in | ❌ No | Content subcategories generated by CreatorDB’s AI model that classifies creators into about 490 dynamic themes based on their content. To get valid topic values for filterName, call /youtube/topics. |
| lastPublishTime | number | >, =, < | ✅ Yes | Time of the last uploaded content, represented as a 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. |
| relatedCreators | string or string[] | =, != | ✅ Yes | YouTube channel ID for searching related creators. |
| Channel Stats | ||||
| totalSubscribers | number | >, =, < | ✅ Yes | The total number of subscribers. |
| totalContents | number | >, =, < | ✅ Yes | The total number of videos uploaded by the creator. |
| totalViews | number | >, =, < | ✅ Yes | Lifetime channel views, the figure YouTube shows on the channel’s About panel. |
| subscriberGrowthIn30d | number | >, =, < | ✅ Yes | The growth rate of subscribers in the past 30 days, rounded to 4th decimal place. |
| joinedDate | number | >, =, < | ✅ Yes | Time when the channel was created, represented as a Unix timestamp in milliseconds. |
| platformScore | number | >, =, < | ✅ Yes | CreatorDB’s score for this creator on this platform, on a 0–1 scale: the creator’s percentile among all creators on the platform, combining audience size, reach, engagement, and growth. For example, 0.99 is the top 1%. Values above 1 match no creators. |
| Video Performance | ||||
| avgRecentVideosViews | number | >, =, < | ✅ Yes | Average views per video across the most recent 20 videos, rounded to an integer. |
| avgVideosViewsAll | number | >, =, < | ✅ Yes | Average views per video across up to the last 800 videos, rounded to an integer. |
| avgRecentVideosViewsGrowth | number | >, =, < | ✅ Yes | Growth rate of average views per video in recent posts. |
| medianRecentVideosViews | number | >, =, < | ✅ Yes | Median views per video across the last 20 videos. |
| medianVideosViewsAll | number | >, =, < | ✅ Yes | Median views per video across the last 800 videos. |
| minRecentVideosViews | number | >, =, < | ✅ Yes | Minimum views among recent videos. |
| maxRecentVideosViews | number | >, =, < | ✅ Yes | Maximum views among recent videos. |
| minVideosViewsAll | number | >, =, < | ✅ Yes | Minimum views among all-time videos. |
| maxVideosViewsAll | number | >, =, < | ✅ Yes | Maximum views among all-time videos. |
| avgRecentVideosLikes | number | >, =, < | ✅ Yes | Average likes per video across the most recent 20 videos, rounded to an integer. |
| avgVideosLikesAll | number | >, =, < | ✅ Yes | Average likes per video across up to the last 800 videos, rounded to an integer. |
| avgRecentVideosLikesGrowth | number | >, =, < | ✅ Yes | Growth rate of average likes per video in recent posts. |
| medianRecentVideosLikes | number | >, =, < | ✅ Yes | Median likes per video across the last 20 videos. |
| medianVideosLikesAll | number | >, =, < | ✅ Yes | Median likes per video across the last 800 videos. |
| minRecentVideosLikes | number | >, =, < | ✅ Yes | Minimum likes among recent videos. |
| maxRecentVideosLikes | number | >, =, < | ✅ Yes | Maximum likes among recent videos. |
| minVideosLikesAll | number | >, =, < | ✅ Yes | Minimum likes among all-time videos. |
| maxVideosLikesAll | number | >, =, < | ✅ Yes | Maximum likes among all-time videos. |
| avgRecentVideosComments | number | >, =, < | ✅ Yes | Average comments per video across the most recent 20 videos, rounded to an integer. |
| avgVideosCommentsAll | number | >, =, < | ✅ Yes | Average comments per video across the last 800 videos, rounded to an integer. |
| avgRecentVideosCommentsGrowth | number | >, =, < | ✅ Yes | Growth rate of average comments per video in recent posts. |
| medianRecentVideosComments | number | >, =, < | ✅ Yes | Median comments per video across the last 20 videos. |
| medianVideosCommentsAll | number | >, =, < | ✅ Yes | Median comments per video across the last 800 videos. |
| minRecentVideosComments | number | >, =, < | ✅ Yes | Minimum comments among recent videos. |
| maxRecentVideosComments | number | >, =, < | ✅ Yes | Maximum comments among recent videos. |
| minVideosCommentsAll | number | >, =, < | ✅ Yes | Minimum comments among all-time videos. |
| maxVideosCommentsAll | number | >, =, < | ✅ Yes | Maximum comments among all-time videos. |
| avgRecentVideosEngagementRate | number | >, =, < | ✅ Yes | Average engagement rate per video across the most recent 20 videos, rounded to the 4th decimal place. Calculated as (likes + comments) / views. |
| avgVideosEngagementRateAll | number | >, =, < | ✅ Yes | Average engagement rate per video across up to the last 800 videos. Rounded to the 4th decimal place. Calculated as (likes + comments) / views. |
| avgRecentVideosEngagementRateGrowth | number | >, =, < | ✅ Yes | Growth rate of average engagement rate per video in recent posts. |
| avgRecentVideosLength | number | >, =, < | ✅ Yes | Average length (in seconds) per video across the most recent 20 videos. |
| avgVideosLengthAll | number | >, =, < | ✅ Yes | Average length (in seconds) per video across the last 800 videos. |
| avgRecentVideosCommentReplyRatio | number | >, =, < | ✅ Yes | The creator’s average reply rate to the top 20 comments per video, across recent videos. Higher value = more interactive audience. Range 0–1. |
| avgVideosCommentReplyRatioAll | number | >, =, < | ✅ Yes | Same as avgRecentVideosCommentReplyRatio, calculated across all-time videos. Based on the last 800 videos. |
| avgRecentVideosSelfCommentRatio | number | >, =, < | ✅ Yes | The creator’s average self-comment rate across recent videos (creator’s own comments / total comments). Higher value = creator actively engages with their audience. Range 0–1. |
| avgVideosSelfCommentRatioAll | number | >, =, < | ✅ Yes | Same as avgRecentVideosSelfCommentRatio, calculated across all-time videos. Based on the last 800 videos. |
| avgRecentVideosCommentLikeRatio | number | >, =, < | ✅ Yes | Ratio of comments to likes across recent videos. Surfaces creators whose audiences engage more deeply (comment) than passively (like). Based on the most recent 20 videos. |
| avgVideosCommentLikeRatioAll | number | >, =, < | ✅ Yes | Same as avgRecentVideosCommentLikeRatio, calculated across all-time videos. Based on the last 800 videos. |
| Shorts Performance | ||||
| avgRecentShortsViews | number | >, =, < | ✅ Yes | Average views per short across the most recent 20 shorts, rounded to an integer. |
| avgShortsViewsAll | number | >, =, < | ✅ Yes | Average views per short across up to the last 800 shorts, rounded to an integer. |
| avgRecentShortsViewsGrowth | number | >, =, < | ✅ Yes | Growth rate of average views per short in recent posts. |
| medianRecentShortsViews | number | >, =, < | ✅ Yes | Median views per short across the last 20 shorts. |
| medianShortsViewsAll | number | >, =, < | ✅ Yes | Median views per short across the last 800 shorts. |
| minRecentShortsViews | number | >, =, < | ✅ Yes | Minimum views among recent shorts. |
| maxRecentShortsViews | number | >, =, < | ✅ Yes | Maximum views among recent shorts. |
| minShortsViewsAll | number | >, =, < | ✅ Yes | Minimum views among all-time shorts. |
| maxShortsViewsAll | number | >, =, < | ✅ Yes | Maximum views among all-time shorts. |
| avgRecentShortsLikes | number | >, =, < | ✅ Yes | Average likes per short across the most recent 20 shorts, rounded to an integer. |
| avgShortsLikesAll | number | >, =, < | ✅ Yes | Average likes per short across up to the last 800 shorts, rounded to an integer. |
| avgRecentShortsLikesGrowth | number | >, =, < | ✅ Yes | Growth rate of average likes per short in recent posts. |
| medianRecentShortsLikes | number | >, =, < | ✅ Yes | Median likes per short across the last 20 shorts. |
| medianShortsLikesAll | number | >, =, < | ✅ Yes | Median likes per short across the last 800 shorts. |
| minRecentShortsLikes | number | >, =, < | ✅ Yes | Minimum likes among recent shorts. |
| maxRecentShortsLikes | number | >, =, < | ✅ Yes | Maximum likes among recent shorts. |
| minShortsLikesAll | number | >, =, < | ✅ Yes | Minimum likes among all-time shorts. |
| maxShortsLikesAll | number | >, =, < | ✅ Yes | Maximum likes among all-time shorts. |
| avgRecentShortsComments | number | >, =, < | ✅ Yes | Average comments per short across the most recent 20 shorts, rounded to an integer. |
| avgShortsCommentsAll | number | >, =, < | ✅ Yes | Average comments per short across up to the last 800 shorts, rounded to an integer. |
| avgRecentShortsCommentsGrowth | number | >, =, < | ✅ Yes | Growth rate of average comments per short in recent posts. |
| medianRecentShortsComments | number | >, =, < | ✅ Yes | Median comments per short across the last 20 shorts. |
| medianShortsCommentsAll | number | >, =, < | ✅ Yes | Median comments per short across the last 800 shorts. |
| minRecentShortsComments | number | >, =, < | ✅ Yes | Minimum comments among recent shorts. |
| maxRecentShortsComments | number | >, =, < | ✅ Yes | Maximum comments among recent shorts. |
| minShortsCommentsAll | number | >, =, < | ✅ Yes | Minimum comments among all-time shorts. |
| maxShortsCommentsAll | number | >, =, < | ✅ Yes | Maximum comments among all-time shorts. |
| avgRecentShortsEngagementRate | number | >, =, < | ✅ Yes | Average engagement rate per short across the most recent 20 shorts, rounded to the 4th decimal place. Calculated as (likes + comments) / views. |
| avgShortsEngagementRateAll | number | >, =, < | ✅ Yes | Average engagement rate per short across up to the last 800 shorts, rounded to the 4th decimal place. Calculated as (likes + comments) / views. |
| avgRecentShortsEngagementRateGrowth | number | >, =, < | ✅ Yes | Growth rate of average engagement rate per short in recent posts. |
| Combined Content Performance | ||||
| avgRecentContentsViews | number | >, =, < | ✅ Yes | Average views across all videos and shorts in recent posts. |
| avgRecentContentsLikes | number | >, =, < | ✅ Yes | Average likes across all content types in recent posts. |
| avgRecentContentsComments | number | >, =, < | ✅ Yes | Average comments across all content types 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. |
| Percentile Rankings | ||||
| avgContentViewsPercentile | number | >, =, < | ✅ Yes | Percentile ranking of average content views compared to all YouTube channels, as a decimal from 0 to 1 (e.g., 0.9 = top 10%). |
| avgContentViewsPercentileGrowth | number | >, =, < | ✅ Yes | Growth rate of average content views percentile ranking. |
| avgContentEngagementPercentile | number | >, =, < | ✅ Yes | Percentile ranking of average content engagement compared to all YouTube channels, as a decimal from 0 to 1 (e.g., 0.9 = top 10%). |
| avgContentEngagementPercentileGrowth | number | >, =, < | ✅ Yes | Growth rate of average content engagement percentile ranking. |
| subscriberCountPercentile | number | >, =, < | ✅ Yes | Percentile ranking of subscriber count, as a decimal from 0 to 1 (e.g., 0.9 = top 10%). |
| subscriberCountPercentileGrowth | number | >, =, < | ✅ Yes | Growth rate of subscriber count percentile ranking. |
| Audience Demographics | ||||
| mainAudienceLocation | string or string[] | =, in | ✅ Yes | Country with the largest audience share. Constraint: Must be in ISO 3166-1 alpha-3 format. |
| mainAudienceAge | string or string[] | =, in | ✅ Yes | Primary age range of the audience. Allowed Values: "13-17", "18-24", "25-34", "35-44", "45-54", "55-64", "65+". |
| mainAudienceGender | string | =, in | ❌ No | Dominant gender group among the audience. Allowed Values: "male", "female". |
| audienceMaleRatio | number | >, =, < | ✅ Yes | Share of male subscribers in the channel’s audience, as a decimal from 0 to 1 (e.g., 0.6 = 60%). |
| audienceFemaleRatio | number | >, =, < | ✅ Yes | Share of female subscribers in the channel’s audience, as a decimal from 0 to 1 (e.g., 0.6 = 60%). |
| Sponsorship | ||||
| hasSponsors | boolean | = | ❌ No | Indicates whether the channel has published sponsored content. |
| Content type | ||||
| isPodcast | boolean | = | ❌ No | true for channels that CreatorDB’s AI classifier labels as podcast channels. Channels that haven’t been classified match neither true nor false. |
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
curl --request POST \
--url https://apiv3.creatordb.app/youtube/search \
--header 'Content-Type: application/json' \
--header 'api-key: <YOUR_API_KEY_HERE>' \
--data '
{
"filters": [
{
"filterName": "totalSubscribers",
"op": ">",
"value": 100000,
"isFuzzySearch": true
}
],
"pageSize": 10,
"offset": 0,
"desc": true,
"sortBy": "totalSubscribers"
}
'
{
"data": {
"creatorList": [
{
"displayName": "🪐🌍Gallivud_prod",
"uniqueId": "@gallivud_prod",
"channelId": "UCMS8ONu5i0tKTyZ4_lLD1DA",
"avatarUrl": "https://yt3.googleusercontent.com/geeG3ok-_7PzCBlXDEW8Ro2m0QNl_XRH4AekEVvPqBhgmrFJbn2iKzn06lSnI2GnkybvaJY7=s900-c-k-c0x00ffffff-no-rj",
"totalSubscribers": 1400000
},
{
"displayName": "🪐MILENA MARS🪐",
"uniqueId": "@milenamars",
"channelId": "UCjTWFYn4s7fzsonX3Jtw_Ig",
"avatarUrl": "https://yt3.googleusercontent.com/kFfAtp8wQM5wTqRzFn1wiZWdcJ5atGU1u-BnzpadbVFQJBThObAYNZTxsagdHnzW5m79G5A4pg=s900-c-k-c0x00ffffff-no-rj",
"totalSubscribers": 2170000
},
{
"displayName": "🩷La Barbie Jimenez 🩷",
"uniqueId": "@labarbiejimenez",
"channelId": "UC2Z5u_Azat1RoqK-7-Sy4Tg",
"avatarUrl": "https://yt3.googleusercontent.com/h6_4n7pOk4AAn93qpxZl0abQZjYtg4PtzxXnsPO3l4wF7p3d8271Q_F_TqeUDsvuQKA6aIPaxYo=s900-c-k-c0x00ffffff-no-rj",
"totalSubscribers": 1050000
},
{
"displayName": "🦋wishkhanna_🦋",
"uniqueId": "@wishkhanna____",
"channelId": "UC32P0rFNpMhz97Oast8Mdgg",
"avatarUrl": "https://yt3.googleusercontent.com/rubd3-FNnl6pEpm5po_t6J67FE0IV_p452ujgAlxs1QITLGzi-nObStp06dbR3Qz96RJ5gm1=s900-c-k-c0x00ffffff-no-rj",
"totalSubscribers": 1450000
},
{
"displayName": "🥜𝐀𝐧𝐲𝐚 𝐂𝐡𝐚𝐧🥜",
"uniqueId": "@yandere79",
"channelId": "UCVYsu-OqwXh9wF9eHERXcNg",
"avatarUrl": "https://yt3.googleusercontent.com/kOFqPM33m-b9YLSSjS499UciWpwZMJ0-MLmTjycnBUoGr3OCF2-yH8lMrT4VDgi4XznVX7TA9w=s900-c-k-c0x00ffffff-no-rj",
"totalSubscribers": 2250000
},
{
"displayName": "🤍cloudy express 🤍",
"uniqueId": "@cloudyexpress-cb3pf",
"channelId": "UCo7-sHv2yP_tk2FFbfwmILQ",
"avatarUrl": "https://yt3.googleusercontent.com/c5pVxWtJhkU12B3D_MS_pfEV-9wpwyxsCHHrOLP67tEQgAf5uNwreDaPHxIqIqS81LIRbjX8w8A=s900-c-k-c0x00ffffff-no-rj",
"totalSubscribers": 1030000
},
{
"displayName": "🙏Jay shri shyam🙏",
"uniqueId": "@bhaktisagar609",
"channelId": "UC2e-a4J25uO7Vqdz5s9D39w",
"avatarUrl": "https://yt3.googleusercontent.com/1onewDKzTDXArcN-SSOogr_-eGczRvnWi2jlcxMGaxSJq9e8DDMgFwfs7BpaXogQwfFt2Cm3=s900-c-k-c0x00ffffff-no-rj",
"totalSubscribers": 1810000
},
{
"displayName": "🙏 Pray Together 🙏",
"uniqueId": "@frastefano",
"channelId": "UCEISS2bKsVnyvPSGvK-q_mg",
"avatarUrl": "https://yt3.googleusercontent.com/lqbSpiP1yWva-3v1pbFlZ--tVLaQJuCwGP1vvoAi75-w-VqJe0QDzUxqtfwUfE25Qem15nxy3w=s900-c-k-c0x00ffffff-no-rj",
"totalSubscribers": 1270000
},
{
"displayName": "🖤BRK",
"uniqueId": "@mr.say3ed",
"channelId": "UCCQ7XwHCZetFk0zJWadP1Ww",
"avatarUrl": "https://yt3.googleusercontent.com/kr5zTRyltQF-7K7iCIiB9iMV1wOmvpRPYvUeIqa_KdxmzRwAe_FdEiS7heUG7bTJLibMP7HHUg=s900-c-k-c0x00ffffff-no-rj",
"totalSubscribers": 1160000
},
{
"displayName": "🖤 everytime BTS 🖤",
"uniqueId": "@everytimebts2517",
"channelId": "UCEi2lZb1oSZ7tDP5vi4U9tg",
"avatarUrl": "https://yt3.googleusercontent.com/YGNUzzRXD7hvz6Swqgs-NR7sZGiuKodJr15sLdf4tYPMyVXvw3M2ZTN9RJ3psNn5sHmJ3dhxxw=s900-c-k-c0x00ffffff-no-rj",
"totalSubscribers": 1110000
}
],
"hasNextPage": true,
"nextOffset": 10
},
"quotaUsed": 1,
"quotaUsedTotal": 1,
"remainingQuota": -1,
"traceId": "f3430ba969f51fc42d633cb4fd00f86d",
"timestamp": 1767923571340,
"errorCode": "",
"errorDescription": "",
"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 ten creators with less than 10,000 subscribers and list their YouTube ID in descending order.- Request example
- Response example
curl --request POST \
--url https://apiv3.creatordb.app/youtube/search \
--header 'Content-Type: application/json' \
--header 'api-key: <YOUR_API_KEY_HERE>' \
--data '
{
"filters": [
{
"filterName": "totalSubscribers",
"op": "<",
"value": 10000,
"isFuzzySearch": true
}
],
"pageSize": 10,
"offset": 0,
"desc": true,
"sortBy": "totalSubscribers"
}
'
{
"data": {
"creatorList": [
{
"displayName": "<string>",
"uniqueId": "<string>",
"channelId": "<string>",
"avatarUrl": "<string>",
"totalSubscribers": 1
}
],
"hasNextPage": true,
"nextOffset": 1
},
"traceId": "<string>",
"timestamp": 123,
"errorCode": "<string>",
"errorDescription": "<string>",
"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 ten YouTube IDs with 10,000 to 100,000 subscribers.- Request example
- Response example
curl --request POST \
--url https://apiv3.creatordb.app/youtube/search \
--header 'Content-Type: application/json' \
--header 'api-key: <YOUR_API_KEY_HERE>' \
--data '
{
"filters": [
{
"filterName": "totalSubscribers",
"op": ">",
"value": 10000,
"isFuzzySearch": true
},
{
"filterName": "totalSubscribers",
"op": "<",
"value": 100000,
"isFuzzySearch": true
}
],
"pageSize": 10,
"offset": 0,
"desc": true,
"sortBy": "displayName"
}
'
{
"data": {
"creatorList": [
{
"displayName": "<string>",
"uniqueId": "<string>",
"channelId": "<string>",
"avatarUrl": "<string>",
"totalSubscribers": 1
}
],
"hasNextPage": true,
"nextOffset": 1
},
"traceId": "<string>",
"timestamp": 123,
"errorCode": "<string>",
"errorDescription": "<string>",
"success": true
}
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
curl --request POST \
--url https://apiv3.creatordb.app/youtube/search \
--header 'Content-Type: application/json' \
--header 'api-key: <YOUR_API_KEY_HERE>' \
--data '
{
"filters": [
{
"filterName": "avgVideosViewsAll",
"op": ">",
"value": 10000,
"isFuzzySearch": true
}
],
"pageSize": 10,
"offset": 0,
"desc": true,
"sortBy": "totalSubscribers"
}
'
{
"data": {
"creatorList": [
{
"displayName": "<string>",
"uniqueId": "<string>",
"channelId": "<string>",
"avatarUrl": "<string>",
"totalSubscribers": 1
}
],
"hasNextPage": true,
"nextOffset": 1
},
"traceId": "<string>",
"timestamp": 123,
"errorCode": "<string>",
"errorDescription": "<string>",
"success": true
}
Using custom filters in Instagram search
Search for Instagram creators using various filter options.
Configuring custom Instagram filter search criteria
Method:POST Description: Search for Instagram creators based on custom filter criteria such as
displayName, follower count, content performance, and more.Important: Request Parameter Limits
- Filter Count: Unlimited number of filter objects. CreatorDB bills filters in blocks of 10 at 1 credit per block. A partial block counts as a full one (1–10 filters = 1 credit, 11–20 = 2, and so on).
- Array Value Limit: When using the
inoperator, the array can contain a maximum of 100 string values. - Page Size: The upper limit for
pageSizeis 100. - Fuzzy Search:
isFuzzySearch: trueis only available for String type fields.
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 filter value. The type depends on the filterName.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 to true for descending order. |
| sortBy | string | No | Field used to sort results. 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 |
|---|---|---|---|---|
| Identity & Profile | ||||
| displayName | string or string[] | =, in | ✅ Yes | The Instagram account name. |
| uniqueId | string or string[] | =, in | ✅ Yes | The Instagram handle. Constraint: Must be 1-30 characters, allowing letters, numbers, dots, and underscores. Can include optional @ prefix (e.g., cristiano or @cristiano). |
| category | string or string[] | =, in | ✅ Yes | The professional account category. |
| country | string or string[] | =, in | ✅ Yes | The creator’s country, estimated by CreatorDB’s location model. Constraint: Must be in ISO 3166-1 alpha-3 format (e.g., TWN, USA). |
| mainLanguage | string or string[] | =, in | ✅ Yes | The primary language used in posts. Constraint: Must be in ISO 639-3 format. |
| languages | string or string[] | =, in | ✅ Yes | All languages used in posts. Constraint: Must be in ISO 639-3 format. |
| secondLanguage | string or string[] | =, in | ✅ Yes | The secondary language used in posts. Constraint: Must be in ISO 639-3 format. |
| hasEmail | boolean | = | ✅ Yes | Is true when the creator has provided an email address. |
| isAccountVerified | boolean | = | ❌ No | true if it is verified by Instagram. |
| Content & Discovery | ||||
| hashtags | string or string[] | =, in | ❌ No | Keywords used in post captions or descriptions. |
| niches | string or string[] | =, in | ❌ No | Granular subcategories of content topics identified by CreatorDB’s AI model. To get valid niche values for filterName, call /instagram/niches. |
| topics | string or string[] | =, in | ❌ No | Content subcategories generated by CreatorDB’s AI model that classifies creators into about 490 dynamic themes based on their content. To get valid topic values for filterName, call /instagram/topics. |
| keywords | string or string[] | =, in | ❌ No | Filter by niche identifiers, prefixed with the source taxonomy. Values must take the form niches|<id> (e.g., niches|id_love_All). |
| taggedCreator | string or string[] | =, in | ❌ No | Tagged creators. |
| relatedCreator | string or string[] | =, in | ❌ No | Creators recommended by Instagram. |
| Account Stats | ||||
| totalFollowers | number | >, =, < | ✅ Yes | Total number of followers. |
| following | number | >, =, < | ✅ Yes | Total number of accounts followed. |
| totalContents | number | >, =, < | ✅ Yes | Total number of image posts and reels. |
| lastPublishTime | number | >, =, < | ✅ Yes | Time of the last uploaded content, represented as a Unix timestamp in milliseconds. |
| imageLastPublishTime | number | >, =, < | ✅ Yes | Time of the most recent image post represented as a Unix timestamp in milliseconds. |
| reelsLastPublishTime | number | >, =, < | ✅ Yes | Time of the most recent reel post represented as a Unix timestamp in milliseconds. |
| followerGrowthIn30d | number | >, =, < | ✅ Yes | Followers growth rate in the past 30 days, rounded to the 4th decimal place. |
| contentsIn30Days | number | >, =, < | ✅ Yes | Number of total contents published in the last 30 days. |
| imagesIn30Days | number | >, =, < | ✅ Yes | Number of image posts published in the last 30 days. |
| reelsIn30Days | number | >, =, < | ✅ Yes | Number of reels published in the last 30 days. |
| platformScore | number | >, =, < | ✅ Yes | CreatorDB’s score for this creator on this platform, on a 0–1 scale: the creator’s percentile among all creators on the platform, combining audience size, reach, engagement, and growth. For example, 0.99 is the top 1%. Values above 1 match no creators. |
| Image Performance | ||||
| avgRecentImagesLikes | number | >, =, < | ✅ Yes | Average number of likes per image post based on recent posts, rounded to an integer. |
| medianRecentImagesLikes | number | >, =, < | ✅ Yes | Median number of likes received on recent image posts. |
| minRecentImagesLikes | number | >, =, < | ✅ Yes | Minimum number of likes among recent image posts. |
| maxRecentImagesLikes | number | >, =, < | ✅ Yes | Maximum number of likes among recent image posts. |
| avgRecentImagesComments | number | >, =, < | ✅ Yes | Average number of comments per image post based on recent posts, rounded to an integer. |
| medianRecentImagesComments | number | >, =, < | ✅ Yes | Median number of comments received on recent image posts. |
| minRecentImagesComments | number | >, =, < | ✅ Yes | Minimum number of comments among recent image posts. |
| maxRecentImagesComments | number | >, =, < | ✅ Yes | Maximum number of comments among recent image posts. |
| avgRecentImagesEngagementRate | number | >, =, < | ✅ Yes | Average engagement rate per image post, rounded to the 4th decimal place. Calculated as (likes + comments) / followers. |
| avgRecentImagesLikesGrowth | number | >, =, < | ✅ Yes | Growth rate of average likes per image in recent posts. |
| avgRecentImagesCommentsGrowth | number | >, =, < | ✅ Yes | Growth rate of average comments per image in recent posts. |
| avgRecentImagesEngagementRateGrowth | number | >, =, < | ✅ Yes | Growth rate of average engagement rate per image in recent posts. |
| Reels Performance | ||||
| avgRecentReelsViews | number | >, =, < | ✅ Yes | Average number of views per reel based on recent reels, rounded to an integer. |
| medianRecentReelsViews | number | >, =, < | ✅ Yes | Median number of views received on recent reels. |
| avgRecentReelsLikes | number | >, =, < | ✅ Yes | Average number of likes per reel based on recent reels, rounded to an integer. |
| medianRecentReelsLikes | number | >, =, < | ✅ Yes | Median number of likes received on recent reels. |
| minRecentReelsLikes | number | >, =, < | ✅ Yes | Minimum number of likes among recent reels. |
| maxRecentReelsLikes | number | >, =, < | ✅ Yes | Maximum number of likes among recent reels. |
| avgRecentReelsComments | number | >, =, < | ✅ Yes | Average number of comments per reel based on recent reels, rounded to an integer. |
| medianRecentReelsComments | number | >, =, < | ✅ Yes | Median number of comments received on recent reels. |
| minRecentReelsComments | number | >, =, < | ✅ Yes | Minimum number of comments among recent reels. |
| maxRecentReelsComments | number | >, =, < | ✅ Yes | Maximum number of comments among recent reels. |
| avgRecentReelsEngagementRate | number | >, =, < | ✅ Yes | Average engagement rate per reel. Calculated as (likes + comments)/ views. Rounded to the 4th decimal place. |
| avgRecentReelsViewsGrowth | number | >, =, < | ✅ Yes | Growth rate of average views per reel in recent posts. |
| avgRecentReelsLikesGrowth | number | >, =, < | ✅ Yes | Growth rate of average likes per reel in recent posts. |
| avgRecentReelsCommentsGrowth | number | >, =, < | ✅ Yes | Growth rate of average comments per reel in recent posts. |
| avgRecentReelsEngagementRateGrowth | number | >, =, < | ✅ Yes | Growth rate of average engagement rate per reel in recent posts. |
| Combined Content Performance | ||||
| avgRecentContentsLikes | number | >, =, < | ✅ Yes | Average likes across all image posts and reels in recent posts. |
| avgRecentContentsComments | number | >, =, < | ✅ Yes | Average comments across all image posts and reels in recent posts. |
| avgRecentContentsEngagementRate | number | >, =, < | ✅ Yes | Average engagement rate across all image posts and reels in recent posts. |
| avgRecentContentsLikesGrowth | number | >, =, < | ✅ Yes | Growth rate of average likes across all image posts and reels in recent posts. |
| avgRecentContentsCommentsGrowth | number | >, =, < | ✅ Yes | Growth rate of average comments across all image posts and reels in recent posts. |
| avgRecentContentsEngagementRateGrowth | number | >, =, < | ✅ Yes | Growth rate of average engagement rate across all image posts and reels in recent posts. |
| Audience Demographics | ||||
| mainAudienceLocation | string or string[] | =, in | ✅ Yes | Country with the largest audience share. Constraint: Must be in ISO 3166-1 alpha-3 format. |
| mainAudienceAge | string or string[] | =, in | ✅ Yes | Primary age range of the audience. Allowed Values: "13-17", "18-24", "25-34", "35-44", "45-54", "55-64", "65+". |
| mainAudienceGender | string or string[] | =, in | ❌ No | Dominant gender group of the audience. Allowed Values: "male", "female". |
| audienceMaleRatio | number | >, =, < | ✅ Yes | Share of male followers in the audience, as a decimal from 0 to 1 (e.g., 0.6 = 60%). |
| audienceFemaleRatio | number | >, =, < | ✅ Yes | Share of female followers in the audience, as a decimal from 0 to 1 (e.g., 0.6 = 60%). |
| Sponsorship | ||||
| hasSponsors | boolean | = | ❌ No | true if there is sponsored content. |
Using filters in TikTok advanced search
Search for TikTok creators using various filter options.
Configuring custom TikTok filter search criteria
Method:POST Description: Search for TikTok creators based on custom filter criteria such as
displayName, follower count, content performance, and more.Important: Request Parameter Limits
- Filter Count: Unlimited number of filter objects. CreatorDB bills filters in blocks of 10 at 1 credit per block. A partial block counts as a full one (1–10 filters = 1 credit, 11–20 = 2, and so on).
- Array Value Limit: When using the
inoperator, the array can contain a maximum of 100 string values. - Page Size: The upper limit for
pageSizeis 100. - Fuzzy Search:
isFuzzySearch: trueis only available for String type fields.
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 | stringnumber string[]boolean | Yes | The filter value. The type depends on the filterName.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 to true for descending order. |
| sortBy | string | No | Field used to sort results. 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 |
|---|---|---|---|---|
| Identity & Profile | ||||
| displayName | string or string[] | =, in | ✅ Yes | The TikTok account name. |
| uniqueId | string or string[] | =, in | ✅ Yes | The TikTok handle. Constraint: Must be 1-100 characters, allowing letters, numbers, dots, hyphens, and underscores. Can include optional @ prefix (e.g., charlidamelio or @charlidamelio). |
| category | string or string[] | =, in | ✅ Yes | Professional account category. |
| country | string or string[] | =, in | ✅ Yes | The country associated with the account. Constraint: Must be in ISO 3166-1 alpha-3 format (e.g., TWN, USA). |
| mainLanguage | string or string[] | =, in | ✅ Yes | The primary language used in posts. Constraint: Must be in ISO 639-3 format. |
| languages | string or string[] | =, in | ✅ Yes | All languages used in posts. Constraint: Must be in ISO 639-3 format. |
| secondLanguage | string or string[] | =, in | ✅ Yes | The secondary language used in posts. Constraint: Must be in ISO 639-3 format. |
| hasEmail | boolean | = | ✅ Yes | Is true when the creator has provided an email address. |
| isAccountVerified | boolean | = | ❌ No | Is true if the account is verified by TikTok. |
| isPrivateAccount | boolean | = | ❌ No | Is true if the account is private. |
| Content & Discovery | ||||
| hashtags | string | =, in | ❌ No | Keywords used in the video caption or descriptions. |
| niches | stringor string[] | =, in | ❌ No | Granular subcategories of content topics identified by CreatorDB’s AI model. |
| topics | string or string[] | =, in | ❌ No | Content subcategories generated by CreatorDB’s AI model that classifies creators into about 490 dynamic themes based on their content. To get valid topic values for filterName, call /tiktok/topics. |
| Account Stats | ||||
| totalFollowers | number | >, =, < | ✅ Yes | Total number of followers. |
| following | number | >, =, < | ✅ Yes | Total number of accounts followed. |
| totalContents | number | >, =, < | ✅ Yes | Total number of videos uploaded. |
| lastPublishTime | number | >, =, < | ✅ Yes | Time the last content was uploaded, represented as a Unix timestamp in milliseconds. |
| followerGrowthIn30d | number | >, =, < | ✅ Yes | Growth rate of followers in the past 30 days, rounded to the 4th decimal place. |
| contentsIn30Days | number | >, =, < | ✅ Yes | Number of videos published in the last 30 days. |
| platformScore | number | >, =, < | ✅ Yes | CreatorDB’s score for this creator on this platform, on a 0–1 scale: the creator’s percentile among all creators on the platform, combining audience size, reach, engagement, and growth. For example, 0.99 is the top 1%. Values above 1 match no creators. |
| Video Performance | ||||
| avgRecentVideosViews | number | >, =, < | ✅ Yes | Average views per video based on recent videos, rounded to an integer. |
| medianRecentVideosViews | number | >, =, < | ✅ Yes | Median views per video based on recent videos. |
| minRecentVideosViews | number | >, =, < | ✅ Yes | Minimum views among recent videos. |
| maxRecentVideosViews | number | >, =, < | ✅ Yes | Maximum views among recent videos. |
| avgRecentVideosLikes | number | >, =, < | ✅ Yes | Average likes per video based on recent videos, rounded to an integer. |
| medianRecentVideosLikes | number | >, =, < | ✅ Yes | Median likes per video based on recent videos. |
| minRecentVideosLikes | number | >, =, < | ✅ Yes | Minimum likes among recent videos. |
| maxRecentVideosLikes | number | >, =, < | ✅ Yes | Maximum likes among recent videos. |
| avgRecentVideosComments | number | >, =, < | ✅ Yes | Average comments per video based on recent videos, rounded to an integer. |
| medianRecentVideosComments | number | >, =, < | ✅ Yes | Median comments among recent videos. |
| minRecentVideosComments | number | >, =, < | ✅ Yes | Minimum number of comments among recent videos. |
| maxRecentVideosComments | number | >, =, < | ✅ Yes | Maximum number of comments among recent videos. |
| avgRecentVideosShares | number | >, =, < | ✅ Yes | Average shares per video based on recent videos, rounded to an integer. |
| medianRecentVideosShares | number | >, =, < | ✅ Yes | Median shares per video based on recent videos. |
| minRecentVideosShares | number | >, =, < | ✅ Yes | Minimum shares among recent videos. |
| maxRecentVideosShares | number | >, =, < | ✅ Yes | Maximum shares among recent videos. |
| avgRecentVideosDuration | number | >, =, < | ✅ Yes | Average duration of recent videos in seconds. |
| avgRecentVideosEngagementRate | number | >, =, < | ✅ Yes | Average engagement rate per video, rounded to 4th decimal place. Calculated as (likes + comments + shares) / views. |
| avgRecentVideosViewsGrowth | number | >, =, < | ✅ Yes | Growth rate of average views per video in recent posts. |
| avgRecentVideosLikesGrowth | number | >, =, < | ✅ Yes | Growth rate of average likes per video in recent posts. |
| avgRecentVideosCommentsGrowth | number | >, =, < | ✅ Yes | Growth rate of average comments per video in recent posts. |
| avgRecentVideosSharesGrowth | number | >, =, < | ✅ Yes | Growth rate of average shares per video in recent posts. |
| avgRecentVideosEngagementRateGrowth | number | >, =, < | ✅ Yes | Growth rate of average engagement rate per video in recent posts. |
| Audience Demographics | ||||
| mainAudienceLocation | stringor string[] | =, in | ✅ Yes | Country with the largest audience share. Constraint: Must be in ISO 3166-1 alpha-3 format. |
| mainAudienceAge | string or string[] | =, in | ✅ Yes | Primary age range of the audience. Allowed Values: "18-24", "25-34", "35-44", "45-54", "55-64", "65+". |
| mainAudienceGender | stringor string[] | =, in | ❌ No | Dominant gender group among the creator’s audience. Allowed Values: "male", "female". |
| audienceMaleRatio | number | >, =, < | ✅ Yes | Share of male followers in the creator’s audience, as a decimal from 0 to 1 (e.g., 0.6 = 60%). |
| audienceFemaleRatio | number | >, =, < | ✅ Yes | Share of female followers in the creator’s audience, as a decimal from 0 to 1 (e.g., 0.6 = 60%). |
About sponsor search
Search for specific brands that have sponsored creators using various filter options.
Using creators as a filter
Search for a specific creator’s sponsors.
Using brands as a search filter
Filter creator sponsors by brand.
Using multiple filters
Filter brands by multiple criteria, such as industry, region, and total sponsored content.
Sponsor search filters
Overview
CreatorDB supports searching for brands that have sponsored YouTube or Instagram creators with predefined filters, such as brand name, industry, region, creator partnerships, estimated spend, and more. When making the API call, you can specify which predefined filters you’d like to add to your search using thePOST methods. By default, search results are listed by total sponsored content in ascending order.Important: Request Parameter Limits
- Filter Count: Unlimited number of filter objects. Each call costs a flat 2 credits, regardless of filter count.
- Array Value Limit: When using the
inoperator, the array can contain a maximum of 100 string values. - Page Size: The upper limit for
pageSizeis 100. - Fuzzy Search:
isFuzzySearch: trueis only available for thenamefield.
API call flow
1
Step 1
Use the Sponsor 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 YouTube or Instagram ID.
2
Step 2
Use the brand name from calling the Sponsor List API to get detailed brand information and performance metrics of their sponsored creators on YouTube and Instagram.
Sponsor search costs a flat 2 credits per call, regardless of how many filter objects the request includes.
Request parameters
| Name | Type | Required | Example | Description |
|---|---|---|---|---|
| filters | object[] | Yes | An array of filter objects that includes: filterName, op, and value. If empty, returns unfiltered results sorted by default configurations. | |
└ filterName | string | Yes | country | The field to apply the filter on. |
└ op | string | Yes | = | The comparison operator. • String fields support: =, in• Number fields support: >, =, <• Boolean fields support: = |
└ value | stringnumber string[]boolean | Yes | USA | The filter value. The type depends on the filterName. For in operator, provide string[]. |
└ isFuzzySearch | boolean | No | true | Default false. When set to true, the filter will perform a fuzzy match. Only applicable for string-type fields. |
| desc | boolean | No | true | Default false (Ascending). Set to true for descending order. |
| sortBy | string | No | name | Field used to sort results. Supported values are: name, totalSponsoredContent, estimatedTotalSpend7d, estimatedTotalSpend30d, estimatedTotalSpend90d. If omitted, the default is relevance when query is provided. Otherwise, the default is totalSponsoredContent. |
| pageSize | number | Yes | 100 | The number of results to return per page. By default, will return 100 results. |
| offset | number | Yes | 0 | The number of records to skip before starting to return results. Default is 0. |
Available filterName & sortBy
The table below lists the available filterName options for the Sponsor Search API. Each entry includes the expected data types, an example value, and indicates whether the field supports sorting. When the Supports sorting column is checkmarked, that field can also be used as a sortBy parameter to sort search results in ascending or descending order.- The sorting behavior depends on the data type. For example, strings are sorted alphabetically.
- Estimated total spend metrics currently only support YouTube data.
| Filter Name | Type | Supported Operators | Supports sorting | Example | Definition |
|---|---|---|---|---|---|
| Brand Identity | |||||
| name | string or string[] | in, = | ✅ Yes | Acer | The brand name or alias. Set isFuzzySearch to true for fuzzy matching. |
| alias | string or string[] | in, = | ❌ No | Nike Inc. | Filter brands by an alias (alternative name). Matching is exact and case-sensitive. To fuzzy-match a brand name, use name with isFuzzySearch set to true. |
| country | string or string[] | in, = | ❌ No | USA | The country the brand is headquartered in, in ISO 3166-1 alpha-3 format. For details, see Country Codes. |
| Sponsorship Activity | |||||
| sponsoringRegion | string or string[] | in, = | ❌ No | USA | The country where the brand’s sponsored creators are primarily located, in ISO 3166-1 alpha-3 format. For details, see Country Codes. |
| sponsoringPlatforms | string or string[] | in, = | ❌ No | youtube | Returns brands that have sponsorships on the specified social media platform. Valid values are: youtube, instagram. |
| sponsoredYoutubeCreatorId | string or string[] | in, = | ❌ No | UCm-X6o81nRsXQTmqpyArkBQ | Returns brands that have sponsored the specified YouTube creator. Accepts YouTube channelId. |
| sponsoredInstagramCreatorId | string or string[] | in, = | ❌ No | mrbeast | Returns brands that have sponsored the specified Instagram creator. Accepts Instagram handles and is not case sensitive. |
| totalSponsoredContent | number | >, <, = | ✅ Yes | 50 | Total number of sponsored content pieces attributed to the brand across indexed platforms. |
| hasActiveCampaign | boolean | = | ❌ No | true | true if the brand has published sponsored content in the last 30 days. |
| Estimated Spend | |||||
| estimatedTotalSpend7d | number | >, <, = | ✅ Yes | 25000 | Estimated amount (USD) spent by this brand on sponsored YouTube creators over a rolling 7-day window. Returns null when no sponsored creator has a price estimate available. |
| estimatedTotalSpend30d | number | >, <, = | ✅ Yes | 100000 | Estimated amount (USD) spent by this brand on sponsored YouTube creators over a rolling 30-day window. Returns null when no sponsored creator has a price estimate available. |
| estimatedTotalSpend90d | number | >, <, = | ✅ Yes | 400000 | Estimated amount (USD) spent by this brand on sponsored YouTube creators over a rolling 90-day window. Returns null when no sponsored creator has a price estimate available. |
Using the creator as a filter in sponsor search
The following examples demonstrate how to use a creator’s platform ID as a filter to retrieve corresponding sponsored information and to query detailed sponsorship performance reports across Instagram and YouTube. You need to enter the creator’s YouTube channel ID or Instagram handle information.By default, CreatorDB lists search results by the brand’s total sponsored content in ascending order.
Filtering by sponsoredYoutubeCreatorId using a single value
By specifying the sponsoredYoutubeCreatorId filter with a YouTube channel ID UCm-X6o81nRsXQTmqpyArkBQ, you can retrieve a list of brands that have sponsored this specific YouTube creator. This allows you to analyze the creator’s sponsorship landscape and identify potential brand partnerships.- Request example
- Response example
curl -X POST "https://apiv3.creatordb.app/sponsor/search" \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'api-key: <YOUR_API_KEY_HERE>' \
--data '{
"filters": [
{
"filterName": "sponsoredYoutubeCreatorId",
"op": "=",
"value": "UCm-X6o81nRsXQTmqpyArkBQ"
}
],
"pageSize": 20,
"offset": 0
}'
{
"data": {
"results": [
{
"brandId": "redmagic.gg",
"name": "Red Magic",
"logo": "https://i.imgur.com/zxuo5yf.jpeg",
"industries": [
"Gaming",
"Consumer Electronics"
],
"country": "CHN"
},
{
"brandId": "opera.com",
"name": "Opera",
"logo": "https://i.imgur.com/btAsAE9.png",
"industries": [
"Information Technology",
"Internet",
"Mobile",
"Software"
],
"country": "NOR"
},
{
"brandId": "msi.com",
"name": "Micro Star International - MSI",
"logo": "https://i.imgur.com/OASiwxr.png",
"industries": [
"Hardware",
"Manufacturing"
],
"country": "TWN"
},
{
"brandId": "infinitynikki.infoldgames.com",
"name": "Infold Games",
"logo": "https://i.imgur.com/o1UEYod.png",
"industries": [
"Video Games",
"Software",
"Human Computer Interaction",
"Digital Media",
"Consumer Electronics"
],
"country": "CHN"
},
{
"brandId": "geoguessr.com",
"name": "GeoGuessr",
"logo": "https://i.imgur.com/RdHIhGY.png",
"industries": [
"Digital Entertainment",
"Gaming"
],
"country": "SWE"
},
{
"brandId": "epicgames.com",
"name": "Epic Games",
"logo": "https://i.imgur.com/rE9OaJl.png",
"industries": [
"Gaming",
"Software",
"Metaverse",
"Digital Entertainment"
],
"country": "USA"
}
],
"totalResults": 6,
"offset": 0,
"pageSize": 20
},
"traceId": "68d377fc9259e2d8f75f2ccf090b9152",
"timestamp": 1776223842261,
"creditsAvailable": 999985,
"creditsUsed": 2,
"errorCode": "",
"errorDescription": "",
"success": true
}
Filtering by sponsoredInstagramCreatorId using multiple values
By specifying in as the operation value, you can search for multiple Instagram creators at the same time. For example, by entering abby.neff and adrianpeachy in the sponsoredInstagramCreatorId filter, you can retrieve a list of brands that have sponsored either of these two popular Instagram creators. This allows you to compare the sponsorship landscapes of multiple creators and identify common brand partnerships or unique sponsors associated with each creator.- Request example
- Response example
curl -X POST "https://apiv3.creatordb.app/sponsor/search" \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'api-key: <YOUR_API_KEY_HERE>' \
--data '{
"filters": [
{
"filterName": "sponsoredInstagramCreatorId",
"op": "in",
"value": ["abby.neff", "adrianpeachy"]
}
],
"pageSize": 20,
"offset": 0
}'
{
"data": {
"results": [
{
"brandId": "shop.lululemon.com",
"name": "Lululemon",
"logo": "https://i.imgur.com/Z9yAIdQ.png",
"industries": [
"Wellness",
"E-Commerce",
"Fitness",
"Lifestyle"
],
"country": "CAN"
}
],
"totalResults": 1,
"offset": 0,
"pageSize": 20
},
"traceId": "864b0045464ccd9481b6e82b5dbdfa85",
"timestamp": 1776232799131,
"creditsAvailable": 999973,
"creditsUsed": 2,
"errorCode": "",
"errorDescription": "",
"success": true
}
Using the brand name as a filter in sponsor search
The following examples demonstrate how to use a competitor’s brand name as a filter to retrieve the brand’s information and industry.By default, CreatorDB lists search results by the brand’s total sponsored content in ascending order.
Filtering by name using a single value
By using the equals operator (=), you can specify which brand data to retrieve from the CreatorDB database.- Request example
- Response example
curl -X POST "https://apiv3.creatordb.app/sponsor/search" \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'api-key: <YOUR_API_KEY_HERE>' \
--data '{
"filters": [
{
"filterName": "name",
"op": "=",
"value": "Adidas"
}
],
"pageSize": 20,
"offset": 0
}'
{
"data": {
"results": [
{
"brandId": "adidas.com",
"name": "Adidas",
"logo": "https://i.imgur.com/4Ha4wep.jpeg",
"industries": [
"Sporting Goods",
"Fashion",
"Fitness",
"Lifestyle",
"Manufacturing",
"Marketing"
],
"country": "DEU"
}
],
"totalResults": 1,
"offset": 0,
"pageSize": 20
},
"traceId": "e0d460deb8bea46c1754d91bda92621a",
"timestamp": 1776224442114,
"creditsAvailable": 999979,
"creditsUsed": 2,
"errorCode": "",
"errorDescription": "",
"success": true
}
Filtering by name using multiple values
By using the in operator, you can specify multiple brand names to retrieve information for several brands at once. This allows you to quickly gather data on multiple competitors and compare their sponsorship activities and industries.- Request example
- Response example
curl -X POST "https://apiv3.creatordb.app/sponsor/search" \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'api-key: <YOUR_API_KEY_HERE>' \
--data '{
"filters": [
{
"filterName": "name",
"op": "in",
"value": ["Adidas", "Puma", "Nike"]
}
],
"pageSize": 20,
"offset": 0
}'
{
"data": {
"results": [
{
"brandId": "puma.com",
"name": "Puma",
"logo": "https://i.imgur.com/d7susAe.png",
"industries": [
"Sporting Goods",
"Fashion",
"Shoes"
],
"country": "DEU"
},
{
"brandId": "nike.com",
"name": "Nike",
"logo": "https://i.imgur.com/lQxXmgm.jpeg",
"industries": [
"Sporting Goods",
"E-Commerce",
"Shoes",
"Consumer Goods"
],
"country": "USA"
},
{
"brandId": "adidas.com",
"name": "Adidas",
"logo": "https://i.imgur.com/4Ha4wep.jpeg",
"industries": [
"Sporting Goods",
"Fashion",
"Fitness",
"Lifestyle",
"Manufacturing",
"Marketing"
],
"country": "DEU"
}
],
"totalResults": 3,
"offset": 0,
"pageSize": 20
},
"traceId": "05761611befed14aad3eb523e5b2f8f9",
"timestamp": 1776237890929,
"creditsAvailable": 999971,
"creditsUsed": 2,
"errorCode": "",
"errorDescription": "",
"success": true
}
Using multiple filters to narrow brand search results
The following example demonstrates how you can use multiple filters, such asindustry, sponsoringRegion, and sponsoredInstagramCreatorId, to narrow the brand search results to find only the most relevant sponsors. In this example, the search results will return up to 20 brands in the ecommerce industry that have sponsored primarily US-based creators. Sponsor search currently only supports Instagram and YouTube data.- Request example
- Response example
curl -X POST "https://apiv3.creatordb.app/sponsor/search" \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'api-key: <YOUR_API_KEY_HERE>' \
--data '{
"filters": [
{
"filterName": "industry",
"op": "in",
"value": ["E-Commerce"]
},
{
"filterName": "sponsoringRegion",
"op": "=",
"value": "USA"
},
{
"filterName": "sponsoredInstagramCreatorId",
"op": "=",
"value": "10eegaming"
}
],
"pageSize": 20,
"offset": 0,
"sortBy": "name",
"desc": true
}'
{
"data":{
"results":[
{
"brandId":"temu.com",
"name":"Temu",
"logo":"https://i.imgur.com/E2Pd6gR.jpeg",
"industries":["E-Commerce","E-Commerce Platforms"],
"country":"USA"
}
],
"totalResults":1,
"offset":0,
"pageSize":20,
"traceId":"6f1ab2aa720148a680d713885b660b4c",
"timestamp":1776222865822,
"creditsAvailable":999987,
"creditsUsed":2,
"errorCode":"",
"errorDescription":"",
"success":true
}
}