Field and Items

You must enable Fractional Calls on your API key. Otherwise, requests that include a fields parameter return a 400 error (FractionalCallsNotEnabled). Full-response calls (without fields) always work. Contact your account manager to enable fractional calls.
You can get the full bundle price of supported API endpoints, by passing [] or omitting the endpoint key. Capped at base price.

Overview

Field and item costs can vary for each CreatorDB data endpoint that supports fractional calls. You can make a request combining multiple fields or items in a fractional call and are never charged more than the full-bundle price. For example:

Content-detail (3)

curl -X POST "https://apiv3.creatordb.app/youtube/search" \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'api-key: YOUR_API_KEY' \
-d '{
  "filters": [
    { "filterName": "totalSubscribers", "op": ">", "value": 10000000 }
  ],
  "fields": {
    "content-detail": {}
  },
  "pageSize": 3,
  "offset": 0
}'

This request enriches each of the 3 search results with the full content-detail bundle.

Base search cost: 1 credit (up to 10 filters)
Enrichment per result: content-detail full bundle = 3 credits (capped at the endpoint base price)
Enrichment total: 3 credits × 3 results = 9 credits

Total: 1 + 9 = 10 credits For details, see the following topics:

Fractional Calls
API Credit Usage (Full-bundle price)

The {platform}/performance-history endpoints (e.g. youtube/performance-history, instagram/performance-history, tiktok/performance-history) does not accept fields and is priced by time range. For details, see Performance History Pricing.

YouTube

The following sections are the accepted fields for the different CreatorDB API endpoints that support YouTube.

`youtube/search`

Search is billed at the base filter rate (1 credit per 10 filters) plus enrichment. Each key below adds that endpoint’s cost per result returned. You cannot subset search’s own return fields. Enrichment cost scales with pageSize.

Key	Description
`profile`	Profile fields to add to each search result.
`performance`	Performance blocks to add to each search result.
`audience`	Audience fields to add to each search result.
`contact`	Contact fields to add to each search result.
`content-detail`	Per-item counts, e.g. `{ "recentVideos": 3 }`. `0`, `null`, or omission returns zero items for that field. Valid field names vary by platform. For details, see Fractional Calls.
`performance-history`	Date range bucket, e.g. `{ "pastDayRange": 90 }`. For pricing details, see Performance history pricing.
`sponsorship`	Per-brand counts, e.g. `{ "sponsorList": 5 }`. `0`, `null`, or omission returns zero brands. Available for YouTube and Instagram search only. For details, see Fractional Calls.

`youtube/profile`

Field	Description
`channelId`	Unique channel ID.
`uniqueId`	Channel handle.
`displayName`	Channel display name.
`categoryBreakdown`	Distribution of the creator’s content by category.
`avatarUrl`	Channel profile picture URL.
`bio`	The channel biography.
`isVerified`	`true` if the account is verified by YouTube.
`hasSponsors`	`true` if there is sponsored content.
`hasMemberOnlyContents`	`true` if there is member-only content.
`country`	The country represented in ISO 3166-1 alpha-3 format. For the country code list, see here.
`mainLanguage`	The primary language used in contents, represented in ISO 639-3 format. For language code list, see here.
`secondLanguage`	The secondary language used in posts, represented in ISO 639-3 format. For language code list, see here.
`languages`	All languages used in contents, represented in ISO 639-3 format. For language code list, see here.
`totalContents`	Total number of videos and shorts.
`totalSubscribers`	Total number of subscribers.
`subscriberGrowth`	Subscriber growth metrics over 7, 30, and 90-day periods (g7, g30, g90).
`hashtags`	Hashtags used in content and related statistics.
`topics`	Content subcategories generated by CreatorDB’s AI model that classifies creators into about 400 dynamic themes based on their content.
`niches`	Granular subcategories of content topics identified by CreatorDB’s AI model, which analyzes and groups keywords, hashtags, and tags used by creators.
`otherLinks`	Linked websites.
`lastPublishTime`	Time the last content was uploaded, represented as a Unix timestamp in milliseconds.
`relatedCreators`	Creators recommended by YouTube, returned as channel IDs.
`lastDbUpdateTime`	Last update time of the creator profile and statistics in the CreatorDB database, represented as a Unix timestamp in milliseconds.

`youtube/contact`

Field	Description
`emails`	Associated email addresses. Empty if unavailable.

The emails field charges the full-bundle price.

`youtube/performance`

Field	Description
`contentCountByDays`	Number of videos published over 7, 30, and 90-day intervals.
`ranking`	Percentile rankings for various performance metrics, benchmarked at the global, country, or language level. A value of `1.0` indicates top 1%, while `0.5` represents the median.
`videosPerformanceRecent`	Performance metrics of the creator’s last 20 YouTube videos.
`shortsPerformanceRecent`	Performance metrics of the creator’s last 20 YouTube shorts.
`videosPerformanceAll`	Creator’s video performance metrics for the last 800 YouTube videos.
`shortsPerformanceAll`	Performance metrics for the last 800 YouTube shorts.
`recentVideosGrowth`	Growth metrics for recent YouTube videos across 7, 30, and 90-day periods.
`recentShortsGrowth`	Growth metrics for recent shorts across 7, 30, and 90-day periods.
`videoPrice`	Estimated pricing analytics for videos. Calculated as $CPM + per-video rate range$ .
`shortsPrice`	Estimated pricing analytics for shorts.

`youtube/audience`

Field	Description
`audienceLocations`	Country locations of the audience, sorted by descending share.
`audienceGender`	Gender distribution of the audience.
`audienceAvgAge`	Average age of the audience, rounded to an integer.
`audienceAgeBreakdown`	Distribution of the audience by age range.

`youtube/content-detail`

The content-detail endpoint comprises two array fields. Each array item is billed as a single unit. Sub-fields are not individually selectable or separately priced. For details, see Get Content Details.

Field	Description
`recentVideos`	Number of recent long-form videos to return.
`recentShorts`	Number of recent shorts to return.

`youtube/sponsorship`

The sponsorship endpoint exposes one array field: sponsorList. Each array entry represents a single sponsoring brand and contains all the brand metadata, sponsored videos, and per-brand performance metrics as a unit. Sub-fields are not individually selectable or separately priced. For details, see the Get Sponsorship Information.

Field	Description
`sponsorList`	Number of sponsoring brands to return.

Instagram

The following sections are the field costs for the different CreatorDB API endpoints that support Instagram.

`instagram/search`

Key	Description
`profile`	Profile fields to add to each search result.
`performance`	Performance blocks to add to each search result.
`performance-history`	Date range bucket, e.g. `{ "pastDayRange": 90 }`. For pricing details, see Performance history pricing.
`audience`	Audience fields to add to each search result.
`contact`	Contact fields to add to each search result.
`content-detail`	Per-item counts, e.g. `{ "recentVideos": 3 }`. `0`, `null`, or omission returns zero items for that field. Valid field names vary by platform. For details, see Fractional Calls.
`sponsorship`	Per-brand counts, e.g. `{ "sponsorList": 5 }`. `0`, `null`, or omission returns zero brands. Available for YouTube and Instagram search only. For details, see Fractional Calls.

`instagram/profile`

Field	Description
`uniqueId`	The Instagram handle.
`displayName`	The Instagram account name.
`category`	The professional account category.
`avatarUrl`	The profile picture URL.
`bio`	The profile biography.
`isBusinessAccount`	`true` if it is a business account.
`isPrivateAccount`	`true` if it is a private account.
`isVerified`	`true` if it is verified by Instagram.
`hasSponsors`	`true` if there is sponsored content.
`country`	The country in ISO 3166-1 alpha-3 format. For the country code list, see here.
`mainLanguage`	The primary language used in posts, represented in ISO 639-3 format. For the language code list, see here.
`secondLanguage`	The secondary language used in posts, represented in ISO 639-3 format. For language code list, see here.
`languages`	All languages used in posts, represented in ISO 639-3 format. For the language code list, see here.
`totalContents`	Total number of image posts and reels.
`totalFollowers`	Total number of followers.
`totalFollowing`	Total number of accounts followed.
`subscriberGrowth`	Follower growth metrics over 7, 30, and 90-day periods (g7, g30, g90).
`hashtags`	Hashtags in Instagram content and usage statistics. Maximum: 100
`niches`	Granular subcategories of content topics identified by CreatorDB’s AI model, which analyzes and groups keywords, hashtags, and tags used by creators.
`otherLinks`	Linked websites.
`lastPublishTime`	Time the last content was uploaded, represented as a Unix timestamp in milliseconds.
`relatedCreators`	Creators recommended by Instagram.
`lastDbUpdateTime`	Last update time of the creator profile and statistics in the CreatorDB database, represented as a Unix timestamp in milliseconds.

`instagram/contact`

Field	Description
`emails`	Associated email addresses. Empty if unavailable.

The emails field charges the full-bundle price.

`instagram/performance`

Field	Description
`contentCountByDays`	Published Instagram posts over 7, 30, and 90-day intervals.
`ranking`	Percentile rankings for various performance metrics, benchmarked at the global, country, or language level. A value of `1.0` indicates top 1%, while `0.5` represents the median.
`recentImagesGrowth`	Growth metrics for recent Instagram image posts across 7, 30, and 90-day periods (g7, g30, g90).
`recentReelsGrowth`	Growth metrics for recent Instagram reels across 7, 30, and 90-day periods (g7, g30, g90).
`imagesPerformanceRecent`	Performance metrics of the creator’s recent Instagram image posts.
`reelsPerformanceRecent`	Performance metrics of the creator’s recent Instagram reels.

`instagram/audience`

Field	Description
`audienceLocations`	Country locations of the audience, sorted by descending share.
`audienceGender`	Gender distribution of the audience.
`audienceAvgAge`	Average age of the audience, rounded to an integer.
`audienceAgeBreakdown`	Distribution of the audience by age range.

`instagram/content-detail`

Field	Description
`recentImages`	Number of recent image posts to return.
`recentReels`	Number of recent reels to return.

`instagram/sponsorship`

Field	Description
`sponsorList`	Number of sponsoring brands to return.

TikTok

The following sections are the field costs for the different CreatorDB API endpoints that support TikTok.

`tiktok/search`

Key	Description
`profile`	Profile fields to add to each search result.
`performance`	Performance blocks to add to each search result.
`performance-history`	Date range bucket, e.g. `{ "pastDayRange": 90 }`. For pricing details, see Performance history pricing.
`audience`	Audience fields to add to each search result.
`contact`	Contact fields to add to each search result.
`content-detail`	Per-item counts, e.g. `{ "recentVideos": 3 }`. `0`, `null`, or omission returns zero items for that field. Valid field names vary by platform. For details, see Fractional Calls.

`tiktok/profile`

Field	Description
`uniqueId`	The TikTok handle.
`displayName`	The TikTok account name.
`category`	Professional account category.
`avatarUrl`	The profile picture URL.
`bio`	The profile biography.
`isBusinessAccount`	`true` if it is a business account.
`isPrivateAccount`	`true` if it is a private account.
`isVerified`	`true` if it is verified by TikTok.
`hasSponsors`	`true` if there is sponsored content.
`country`	The country in ISO 3166-1 alpha-3 format. For the country code list, see here.
`mainLanguage`	The primary language used in posts, represented in ISO 639-3 format. For the language code list, see here.
`languages`	All languages used in posts, represented in ISO 639-3 format. For the language code list, see here.
`secondLanguage`	The secondary language used in posts, represented in ISO 639-3 format. For language code list, see here.
`totalContents`	Total number of videos.
`totalFollowing`	Total number of accounts followed.
`totalFollowers`	Total number of followers.
`subscriberGrowth`	Follower growth metrics over 7, 30, and 90-day periods (g7, g30, g90).
`hashtags`	Hashtags used in TikTok posts and usage statistics.
`niches`	Granular subcategories of content topics identified by CreatorDB’s AI model, which analyzes and groups keywords, hashtags, and tags used by creators.
`otherLinks`	Linked websites.
`lastPublishTime`	Time the last content was uploaded, represented as a Unix timestamp in milliseconds.
`lastDbUpdateTime`	Last update time of the creator profile and statistics in the CreatorDB database, represented as a Unix timestamp in milliseconds.

`tiktok/contact`

Field	Description
`emails`	Associated email addresses. Empty if unavailable.

The emails field charges the full-bundle price.

`tiktok/performance`

Field	Description
`contentCountByDays`	Published TikTok content over 7, 30, and 90-day intervals.
`ranking`	Percentile rankings for various performance metrics, benchmarked at the global, country, or language level. A value of `1.0` indicates top 1%, while `0.5` represents the median.
`recentVideosGrowth`	Growth metrics for recent videos across 7, 30, and 90-day periods (g7, g30, g90).
`videosPerformanceRecent`	Performance metrics of the creator’s recent TikTok videos.

`tiktok/audience`

Field	Description
`audienceLocations`	Country locations of the audience, sorted by descending share.
`audienceGender`	Gender distribution of the audience.
`audienceAvgAge`	Average age of the audience, rounded to an integer.
`audienceAgeBreakdown`	Distribution of the audience by age range.

`tiktok/content-detail`

The content-detail endpoint comprises one array field. Each array item is billed as a single unit. Sub-fields are not individually selectable or separately priced. For details, see Get Content Details.

Field	Description
`recentVideos`	Number of recent videos to return.

The field recentVideos is a single content array that covers all available TikTok content format, it does not distinguish between images, reels, shorts, or videos.

Getting Started

User Guides

API Endpoints

Filter Value References

Troubleshooting and FAQs

Overview

YouTube

`youtube/search`

`youtube/profile`

`youtube/contact`

`youtube/performance`

`youtube/audience`

`youtube/content-detail`

`youtube/sponsorship`

Instagram

`instagram/search`

`instagram/profile`

`instagram/contact`

`instagram/performance`

`instagram/audience`

`instagram/content-detail`

`instagram/sponsorship`

TikTok

`tiktok/search`

`tiktok/profile`

`tiktok/contact`

`tiktok/performance`

`tiktok/audience`

`tiktok/content-detail`

​Overview

​YouTube

​youtube/search

​youtube/profile

​youtube/contact

​youtube/performance

​youtube/audience

​youtube/content-detail

​youtube/sponsorship

​Instagram

​instagram/search

​instagram/profile

​instagram/contact

​instagram/performance

​instagram/audience

​instagram/content-detail

​instagram/sponsorship

​TikTok

​tiktok/search

​tiktok/profile

​tiktok/contact

​tiktok/performance

​tiktok/audience

​tiktok/content-detail

Overview

YouTube

`youtube/search`

`youtube/profile`

`youtube/contact`

`youtube/performance`

`youtube/audience`

`youtube/content-detail`

`youtube/sponsorship`

Instagram

`instagram/search`

`instagram/profile`

`instagram/contact`

`instagram/performance`

`instagram/audience`

`instagram/content-detail`

`instagram/sponsorship`

TikTok

`tiktok/search`

`tiktok/profile`

`tiktok/contact`

`tiktok/performance`

`tiktok/audience`

`tiktok/content-detail`