Using Content Search

Overview

CreatorDB supports searching YouTube, Instagram, and TikTok content. Search for specific videos, shorts, streams, reels, and image posts across every creator in the CreatorDB database. Each result carries the content’s own metadata and engagement metrics, plus a short summary about the content creator. This is the inverse of creator search.

Creator search: Answers “which creators match my criteria?” and returns a list of creators.
Content search: Answers “which posts match my criteria?” and returns a list of posts.

Use content search when the thing you are looking for is a post: a video sponsored by a competitor’s brand, a reel using a hashtag you are tracking, or the top-performing shorts in a category this week. To find creators instead, see Configuring Custom Search Filters and Examples. To pull a known creator’s recent posts, use that platform’s content-detail endpoint.

Before you start

Get an API key. For details, see Authentication.
Read Credit cost. The price of each call depends on the time window you search, whether you search caption or description text, and whether you limit results to larger creators. You can work out the price before you send the request.
Decide which platform you are searching. Cross-platform content search is not supported. Each platform has its own endpoint and its own filter allowlist.

How content search works

Send a POST request to the content-search endpoint for the platform you want:

POST https://apiv3.creatordb.app/youtube/content-search
POST https://apiv3.creatordb.app/instagram/content-search
POST https://apiv3.creatordb.app/tiktok/content-search

Every request requires a filters array, a pageSize, and an offset. By default, results are sorted by publishTime in descending order (newest first). Set sortBy to change the order. Content search covers the recent posts that CreatorDB stores for each creator, not every post a creator has ever published. A request with no time window searches content published in the last 30 days. For details, see Searching a time window.

Request parameters

These parameters are the same on YouTube, Instagram, and TikTok.

Name	Type	Required	Description
`filters`	object[]	Yes	Filter objects, each containing `filterName`, `op`, and `value`. Accepted `filterName` values differ per platform. For details, see the platform sections below.
`filters[].filterName`	string	Yes	The field to filter on. Must be a value from that platform’s allowlist.
`filters[].op`	string	Yes	The comparison operator: `in`, `>`, `=`, or `<`. - String fields accept `=` and `in`. - Number fields accept `>`, `=`, and `<`. - Boolean fields accept `=`.
`filters[].value`	string / number / string[] / boolean	Yes	The value to compare against. The type depends on the `filterName`. The `in` operator takes a `string[]`. The `=` operator on a string field takes a `string`.
`filters[].isFuzzySearch`	boolean	No	Set to `true` to match text anywhere in the field instead of the whole value. Only available on the free-text filters: `description`, `hashtag`, `creatorDisplayName`, `creatorBio`, and on YouTube `title`. With `in`, matches content that contains any of the values. For details, see Matching text.
`timeRange`	object	No	The publish-date range to search, as absolute times. Without `timeRange` or a `publishTime` filter, the search covers the last 30 days. For details, see Searching a time window.
`timeRange.from`	number	Yes, when you send `timeRange`	Start of the range, as a Unix timestamp in milliseconds. Inclusive.
`timeRange.to`	number	No	End of the range, as a Unix timestamp in milliseconds. Exclusive. Defaults to the time of the request.
`sortBy`	string	No	The field to sort by. Only some fields are sortable. For details, see the Sortable column in each platform’s filter tables. Default is `publishTime`.
`desc`	boolean	No	Sort order for results. `true` for descending, `false` for ascending. Default is `true`.
`pageSize`	number	Yes	The number of results per page.
`offset`	number	Yes	The number of records to skip before returning results. Use this to paginate.

Request parameter limits

Filter count: At least 1 and at most 10 filter objects per request.
Array value limit: When using the in operator, the array must contain at least 1 and at most 100 string values.
Page size: The upper limit for pageSize is 100.
Fuzzy search: isFuzzySearch: true is only available on the free-text filters listed above.
Fuzzy in: With isFuzzySearch: true, the in operator takes at most 10 values.
publishTime: At most 36500 days.

Searching a time window

Every content search covers a publish-time window. The window decides which content can match, and its length is one of the inputs to the price. If you don’t set one, the search covers the last 30 days. You set it in two ways, and you can combine them.

timeRange takes absolute times: { "from": 1788220800000, "to": 1790812800000 }. Both values are Unix timestamps in milliseconds. from is inclusive and to is exclusive, so the range is [from, to). If you leave out to, the range ends at the time of the request.
The publishTime filter takes a number of days before the time of the request. { "filterName": "publishTime", "op": "<", "value": 30 } means the last 30 days.

The effective window

The window CreatorDB searches, and prices, is the overlap of timeRange and every publishTime filter in the request. This is the effective window. A request with only publishTime filters has an effective window too.

What you send	Effective window	Length used for pricing
`timeRange` from September 1 to October 1	September 1 to October 1	30 days
`timeRange` with `from` only	`from` up to the time of the request	From `from` to the time of the request
`publishTime < 14`	The last 14 days	14 days
`publishTime = 7`	The 24 hours that end 7 days ago	1 day
`publishTime > 30`	Everything older than 30 days, with no start	Longer (no start)
`timeRange` for the last 90 days and `publishTime < 30`	The last 30 days	30 days
No `timeRange` and no `publishTime`	The last 30 days (the default)	30 days

If the effective window is empty, for example because timeRange and publishTime don’t overlap, the request returns 400 VALIDATION_ERROR. It isn’t billed. For details, see Common errors.

The applied window in the response

Every response returns the window that was searched in data.timeRange, with to filled in and any publishTime filter applied. Use it to confirm what you searched and paid for.

isDefault is true when the request set neither timeRange nor a publishTime filter, so the search used the 30-day default.
from is null when the window has no start, for example a request with only publishTime > 30.

"timeRange": {
    "from": 1788220800000,
    "to": 1790812800000,
    "isDefault": false
}

To get the 7-day price for “the last 7 days”, use publishTime < 7, or send both from and to. If you compute from as “now minus 7 days” in your code and leave out to, the window is measured up to the moment the request arrives, which is slightly longer than 7 days, so it’s priced in the 30-day tier.

Two kinds of filters

Every content-search allowlist is split into two groups, and you can combine them freely in a single request.

Content-level filters apply to the post itself: how many views it got, when it was published, which hashtags it uses, whether it is sponsored.
Creator-level filters apply to the account that published it: follower count, country, niche, audience demographics.

Combining the two is what makes the endpoint useful. “Reels with over 5,000 likes” is a content-level query. Adding “posted by US creators with a majority-female audience aged 18-24” layers creator-level filters onto the same call.

Matching text

isFuzzySearch: true is accepted only on the free-text filters: description, hashtag, creatorDisplayName, creatorBio, and on YouTube title. On any other filter, the request returns 400 VALIDATION_ERROR. To find content that mentions any of several phrases, use in with isFuzzySearch: true. For example, this filter matches captions that mention either brand:

{ "filterName": "description", "op": "in", "value": ["gymshark", "alphalete"], "isFuzzySearch": true }

A fuzzy in takes at most 10 values. These filters ignore letter case on every platform: title, hashtag, partneredBrands, creatorDisplayName, creatorBio, and creatorCategory. description ignores case and spaces.

Searching one creator’s content

To search within a single creator’s content, add the creator ID filter:

Platform	Filter	Value
YouTube	`channelId`	The channel ID, such as `UCX6OQ3DkcsbYNE6H8uQQuVA`.
Instagram	`uniqueId`	The handle, such as `cristiano`. A leading `@` and letter case are ignored.
TikTok	`uniqueId`	The handle, such as `khaby.lame`. A leading `@` and letter case are ignored.

The filter accepts = for one creator or in for several. Combine it with any other filter, for example to find every sponsored post by one creator over the past year. It doesn’t change the price.

Filter behavior to know before you start

Several filters behave differently from what their names suggest. Open any that apply before building a query.

publishTime counts days, not timestamps

The publishTime filter accepts a number of days ago, not a Unix timestamp. To find content from the last 30 days, use { "filterName": "publishTime", "op": "<", "value": 30 }. For absolute dates, use timeRange.The publishTime field in the response is a Unix timestamp in milliseconds. The filter and the response field use different units.

description matching ignores case and spaces

The description filter searches the post text, and the text it searches differs per platform.

Platform	`description` searches
YouTube	The video description. To search the video title, use the `title` filter.
Instagram	The post caption, on every post type.
TikTok	The video caption.

Matching ignores letter case and spaces, so "Promo Code" and "promocode" match the same text.

With isFuzzySearch: true, the value matches anywhere in the text. This is what you want for keyword searches.
Without isFuzzySearch, the value must match the whole text, so an exact description match rarely returns anything.

audienceAvgAge takes an age range, not an average

Despite its name, the audienceAvgAge filter takes the creator’s primary audience age range as a string, such as "18-24". It does not take an average age.The /{platform}/audience endpoint returns a field with the same name, audienceAvgAge, as an integer average age, such as 30. Don’t pass that integer to this filter.

followers uses a daily snapshot

The followers filter compares against a snapshot of each creator’s follower count that CreatorDB refreshes once a day. The follower count returned in each result (creator.totalSubscribers on YouTube, creator.totalFollowers on Instagram and TikTok) is read from the creator’s current record, so it can differ slightly from the value the filter used. A creator just above your followers threshold can show a count just below it, and the other way around.

Performance ratios compare a creator against themselves

performanceViews, performanceLikes, performanceDiggs, and performanceEngagement are ratios against that creator’s own average, not against the platform, the category, or any other creator.A value of 1.5 means the content performed 50% above the average for the account that posted it. Filtering on performanceEngagement > 1.2 finds posts that outperformed their own channel, which surfaces breakout content from small accounts as readily as from large ones.

Sponsored content is detected differently on each platform

Platform	How `isSponsored` is determined
YouTube	Classified as sponsored by a CreatorDB AI model.
Instagram	Instagram’s native sponsor-tag metadata is present. This is the same definition used by `/instagram/content-detail` and `/instagram/sponsorship`, but those endpoints don’t mark posts published in the last 4 days as sponsored. A new sponsored post can return `isSponsored: true` in content search and `false` in the other two endpoints.
TikTok	Not available. TikTok sponsored-content detection is not built, so `isSponsored` and `partneredBrands` are not filterable and are not returned.

partneredBrands accepts a brand ID, not a brand name

Brand IDs are typically the brand’s primary domain. Filter for Acer with "value": "acer.com", not "Acer". The same IDs are returned in the partneredBrands response field.

Post types differ per platform

The postType filter accepts different values on YouTube and Instagram, and TikTok has no postType filter at all because it returns only videos. Any other value returns 400 VALIDATION_ERROR.

Platform	Accepted `postType` values
YouTube	`video`, `shorts`, `stream`
Instagram	`reel`, `slideshow`, `video`
TikTok	Not applicable

On Instagram, both single-image posts and multi-image carousels are returned as slideshow. The response doesn’t distinguish between them. Passing postType: video on Instagram only matches some videos, since many videos are stored as slideshow.On YouTube and Instagram, postType also affects the price.

Credit cost

Content search is priced per call. The price comes from your request alone, not from how many results come back, so you can work it out before you send the request. Every call costs at least 1 credit.

What sets the price

Input	How it’s read from your request
Time window	The length of the effective window: 7 days or less, 30 days or less, 90 days or less, 365 days or less, or longer. A request with no `timeRange` and no `publishTime` filter uses the 30-day default and the 30 days or less price. A window with no start, such as `publishTime > 30` on its own, is priced as longer. The comparison is exact to the millisecond, so a window 1 ms over 30 days is in the 90-day tier.
`description` filter	Whether any filter in the request has `filterName: "description"`. Searching caption or description text costs more.
Creator floor	The highest `followers` value used with the `>` operator. 100,000 or higher picks the 100K+ price. Anything lower, or no `followers >` filter, picks the all creators price. `followers <` and `followers =` don’t count.
Content type (YouTube and Instagram only)	The `postType` filter. On YouTube: `shorts` for Shorts, or `video`, `stream`, or both for Long videos. On Instagram: `reel` for Reels, or `slideshow`, `video`, or both for Posts. A `postType` filter that mixes the two groups, such as `shorts` with `video`, or no `postType` filter, uses the Any type price.

Prices by platform

YouTube
Instagram
TikTok

Credits per call for POST /youtube/content-search.

Content type	Time window	No `description`, all creators	No `description`, 100K+	With `description`, all creators	With `description`, 100K+
Any type	7 days or less	1	1	7	3
Any type	30 days or less	3	1	17	6
Any type	90 days or less	5	2	32	11
Any type	365 days or less	10	4	58	21
Any type	Longer, or no start	15	7	97	41
Shorts	7 days or less	1	1	2	1
Shorts	30 days or less	1	1	5	2
Shorts	90 days or less	2	1	10	4
Shorts	365 days or less	5	2	18	9
Shorts	Longer, or no start	7	5	34	24
Long videos	7 days or less	1	1	5	2
Long videos	30 days or less	2	1	12	4
Long videos	90 days or less	3	1	23	8
Long videos	365 days or less	6	2	43	14
Long videos	Longer, or no start	10	5	77	31

Credits per call for POST /instagram/content-search.

Content type	Time window	No `description`, all creators	No `description`, 100K+	With `description`, all creators	With `description`, 100K+
Any type	7 days or less	1	1	6	2
Any type	30 days or less	4	1	17	5
Any type	90 days or less	8	2	33	8
Any type	365 days or less	15	4	56	13
Any type	Longer, or no start	28	12	92	34
Reels	7 days or less	1	1	3	1
Reels	30 days or less	3	1	9	3
Reels	90 days or less	5	1	17	5
Reels	365 days or less	9	3	27	8
Reels	Longer, or no start	18	9	46	22
Posts	7 days or less	1	1	3	1
Posts	30 days or less	2	1	9	2
Posts	90 days or less	4	1	18	4
Posts	365 days or less	9	2	34	8
Posts	Longer, or no start	21	12	65	29

Credits per call for POST /tiktok/content-search. TikTok has no content-type input.

Time window	No `description`, all creators	No `description`, 100K+	With `description`, all creators	With `description`, 100K+
7 days or less	1	1	1	1
30 days or less	2	1	4	2
90 days or less	5	1	9	2
365 days or less	9	2	17	4
Longer, or no start	16	5	28	7

Working out a price

Take this YouTube request:

{
    "filters": [
        { "filterName": "description", "op": "=", "value": "promo code", "isFuzzySearch": true },
        { "filterName": "followers", "op": ">", "value": 100000 }
    ],
    "timeRange": { "from": 1788220800000, "to": 1790812800000 },
    "pageSize": 100,
    "offset": 0
}

Time window: timeRange covers September 1 to October 1, 2026, which is exactly 30 days, so it’s in the 30 days or less tier.
description filter: Present.
Creator floor: followers > 100000, so 100K+.
Content type: No postType, so Any type.

The price is 6 credits. The same search without the followers filter costs 17 credits. Limited to Shorts with postType: "shorts", it costs 2. Without timeRange, it searches the last 30 days, which is in the same tier, so the price stays 6.

How to lower the cost

Search a shorter window. Shorter windows cost less. A request with no window searches the last 30 days. A 7-day window costs less, and a window longer than 30 days, or one with no start, costs more.
Add a 100K+ creator floor. If you only care about larger creators, add { "filterName": "followers", "op": ">", "value": 100000 }. On windows longer than 30 days, this often cuts the price by half or more.
Pick one content type. On YouTube and Instagram, searching only Shorts, long videos, reels, or posts costs less than searching every type.
Search text only when you need it. A description filter usually costs several times more than the same request without it. On YouTube, if the word you’re looking for is likely in the video title, use the title filter instead. title doesn’t add to the price.

Empty results and pagination

A search that matches nothing is still billed. The price is for running the search, not for the results, so an empty contentList costs the same as a full one.
Every page is billed. Each call with a new offset is a new search and bills the full price again. Paging through 10 pages of a 6-credit search costs 60 credits.
Failed requests aren’t billed. A request rejected with 400 VALIDATION_ERROR, including an empty effective window, uses no credits.

For pricing across all endpoints, see API Credit Usage.

What you get back

All three platforms return the same envelope: a contentList array, plus pagination fields.

Field	Description
`data.contentList`	The matching content items.
`data.totalResults`	The approximate number of items matching your filters, across all pages.
`data.hasNextPage`	`true` if more results are available.
`data.nextOffset`	The `offset` value to send in your next request. `0` when there is no next page.
`data.timeRange`	The effective window that was searched, as `{ from, to, isDefault }`. `from` and `to` are Unix milliseconds, and `from` is `null` when the window has no start. `isDefault` is `true` when the search used the 30-day default. Always returned.
`creditsUsed`	The credits this call cost. Matches the price tables in Credit cost.

totalResults is an estimate. It can count content that can no longer be loaded, for example because the post was removed. Each page returns pageSize items when that many matches remain, and nextOffset can be more than offset plus pageSize because it skips over content that couldn’t be loaded. Always page with the returned nextOffset instead of calculating the next offset yourself.

CreatorDB excludes content published in the last 4 days from aggregated performance metrics, but that exclusion does not apply to content search. Recently published content does appear in your results. Each item in contentList includes a creator object. This is a lightweight summary that includes the handle or channel ID, display name, avatar, and follower count. For full creator details, call the /{platform}/profile endpoint with the ID returned here.

Filter names and response field names

Some filters use a different name from the response field that holds the same data.

Filter	Response field	Platforms
`postType`	`contentType`	YouTube, Instagram
`hashtag`	`hashtags`	All
`engagement`	`engagementRate`	All
`diggs`	`likes`	TikTok
`creatorDisplayName`	`creator.displayName`	All
`followers`	`creator.totalSubscribers`	YouTube
`followers`	`creator.totalFollowers`	Instagram, TikTok

Content search by platform

YouTube
Instagram
TikTok

YouTube content search

Method: POST
Endpoint: https://apiv3.creatordb.app/youtube/content-search

Content-level filters

Name	Type	Example	Sortable	Description
`postType`	string	`video`	No	Content type: `video`, `shorts`, or `stream`. Also sets the content-type price.
`title`	string or string[]	`minecraft tutorial`	No	The video title. Ignores case. Supports fuzzy search.
`description`	string or string[]	`sponsored by`	No	The video description. Ignores case and spaces. Supports fuzzy search. Uses the `description` prices.
`hashtag`	string or string[]	`#gaming`	No	A hashtag used in the video title or description. Ignores case. Supports fuzzy search.
`publishTime`	number	`30`	Yes	Recency in days ago. `< 30` means the last 30 days.
`views`	number	`1000000`	Yes	The number of views.
`likes`	number	`50000`	Yes	The number of likes.
`comments`	number	`1000`	Yes	The number of comments.
`engagement`	number	`0.05`	Yes	The engagement rate of the content.
`isSponsored`	boolean	`true`	No	`true` if a CreatorDB AI model classifies the content as sponsored.
`partneredBrands`	string or string[]	`acer.com`	No	Brand IDs associated with the sponsored content. Ignores case.
`lengthSec`	number	`600`	Yes	The video duration in seconds.
`language`	string or string[]	`eng`	No	The content language in ISO 639-3. For details, see Language Codes.
`category`	string or string[]	`Gaming`	No	The YouTube-defined content category. For details, see YouTube Channel Categories.
`performanceViews`	number	`1.5`	Yes	View performance against the creator’s average.
`performanceEngagement`	number	`1.2`	Yes	Engagement performance against the creator’s average.

Creator-level filters

Name	Type	Example	Sortable	Description
`channelId`	string or string[]	`UCX6OQ3DkcsbYNE6H8uQQuVA`	No	The channel ID. Use it to search one creator’s content.
`creatorDisplayName`	string or string[]	`MrBeast`	No	The channel display name. Supports fuzzy search.
`creatorBio`	string or string[]	`gaming`	No	The channel biography text. Supports fuzzy search.
`country`	string or string[]	`USA`	No	The creator’s country in ISO 3166-1 alpha-3. For details, see Country Codes.
`creatorLanguage`	string or string[]	`eng`	No	The channel’s main language in ISO 639-3. For details, see Language Codes.
`creatorCategory`	string or string[]	`Gaming`	No	The channel’s content category. Ignores case. For details, see YouTube Channel Categories.
`followers`	number	`1000000`	Yes	The creator’s subscriber count, from a daily snapshot. A `>` value of 100,000 or higher uses the 100K+ prices.
`avgEngagement`	number	`0.05`	No	The creator’s average engagement rate.
`contentTopics`	string or string[]	`id_freegames_Gaming`	No	CreatorDB’s AI-generated content topic.
`contentNiches`	string or string[]	`id_roblox_Gaming`	No	CreatorDB’s AI-generated content niche (more granular than topics).
`audienceLocation`	string or string[]	`USA`	No	The creator’s top audience country in ISO 3166-1 alpha-3. For details, see Country Codes.
`audienceAvgAge`	string or string[]	`18-24`	No	The primary audience age range: `13-17`, `18-24`, `25-34`, `35-44`, `45-54`, `55-64`, or `65+`. Not an average age.
`audienceMaleRatio`	number	`0.6`	No	The proportion of male subscribers, from 0 to 1.
`audienceFemaleRatio`	number	`0.4`	No	The proportion of female subscribers, from 0 to 1.
`isVerified`	boolean	`true`	No	`true` if the account is verified by YouTube.

YouTube engagement rate is calculated as (likes + comments) / views, and the response rounds engagementRate to four decimal places.

Request example
Response example

Find high-performing sponsored long videos from the last 30 days, posted by channels with over 100,000 subscribers. Long videos, 30 days or less, no description, 100K+: 1 credit.

curl -X POST "https://apiv3.creatordb.app/youtube/content-search" \
--header 'Content-Type: application/json' \
--header 'api-key: <YOUR_API_KEY_HERE>' \
-d '{
    "filters": [
        { "filterName": "isSponsored", "op": "=", "value": true },
        { "filterName": "views", "op": ">", "value": 1000000 },
        { "filterName": "publishTime", "op": "<", "value": 30 },
        { "filterName": "postType", "op": "=", "value": "video" },
        { "filterName": "followers", "op": ">", "value": 100000 }
    ],
    "sortBy": "views",
    "desc": true,
    "pageSize": 20,
    "offset": 0
}'

Find every video that mentions “promo code” in its description during September 2026, from channels with over 100,000 subscribers. Any type, 30 days or less, with description, 100K+: 6 credits.

curl -X POST "https://apiv3.creatordb.app/youtube/content-search" \
--header 'Content-Type: application/json' \
--header 'api-key: <YOUR_API_KEY_HERE>' \
-d '{
    "filters": [
        { "filterName": "description", "op": "=", "value": "promo code", "isFuzzySearch": true },
        { "filterName": "followers", "op": ">", "value": 100000 }
    ],
    "timeRange": { "from": 1788220800000, "to": 1790812800000 },
    "sortBy": "views",
    "desc": true,
    "pageSize": 100,
    "offset": 0
}'

Find every video sponsored by a specific brand in the last 90 days. Any type, 90 days or less, no description, all creators: 5 credits.

curl -X POST "https://apiv3.creatordb.app/youtube/content-search" \
--header 'Content-Type: application/json' \
--header 'api-key: <YOUR_API_KEY_HERE>' \
-d '{
    "filters": [
        { "filterName": "partneredBrands", "op": "=", "value": "acer.com" },
        { "filterName": "publishTime", "op": "<", "value": 90 }
    ],
    "sortBy": "views",
    "desc": true,
    "pageSize": 20,
    "offset": 0
}'

Find trending shorts carrying a hashtag this week, from creators reaching a specific audience. Shorts, 7 days or less, no description, all creators: 1 credit.

curl -X POST "https://apiv3.creatordb.app/youtube/content-search" \
--header 'Content-Type: application/json' \
--header 'api-key: <YOUR_API_KEY_HERE>' \
-d '{
    "filters": [
        { "filterName": "postType", "op": "=", "value": "shorts" },
        { "filterName": "hashtag", "op": "=", "value": "#gaming" },
        { "filterName": "audienceAvgAge", "op": "=", "value": "18-24" },
        { "filterName": "views", "op": ">", "value": 500000 },
        { "filterName": "publishTime", "op": "<", "value": 7 }
    ],
    "sortBy": "engagement",
    "desc": true,
    "pageSize": 20,
    "offset": 0
}'

Response to the first request example:

{
    "data": {
        "contentList": [
            {
                "contentId": "FbCF_H4ZD64",
                "contentType": "video",
                "title": "I hosted an ADMIN ABUSE on GROW A GARDEN",
                "description": "Thanks @JandelTheGuy play grow a garden here...",
                "thumbnail": "https://i.ytimg.com/vi/FbCF_H4ZD64/hqdefault.jpg",
                "url": "https://www.youtube.com/watch?v=FbCF_H4ZD64",
                "publishTime": 1755273600000,
                "lengthSec": 873,
                "isSponsored": true,
                "partneredBrands": ["acer.com"],
                "views": 5009695,
                "likes": 153000,
                "comments": 15182,
                "engagementRate": 0.0336,
                "hashtags": ["#vlog"],
                "language": "eng",
                "category": "Gaming",
                "creator": {
                    "channelId": "UCm-X6o81nRsXQTmqpyArkBQ",
                    "displayName": "Flamingo",
                    "avatarUrl": "https://yt3.googleusercontent.com/...",
                    "totalSubscribers": 13900000
                }
            }
        ],
        "totalResults": 1250,
        "hasNextPage": true,
        "nextOffset": 20,
        "timeRange": {
            "from": 1748140453635,
            "to": 1750732453635,
            "isDefault": false
        }
    },
    "creditsUsed": 1,
    "creditsAvailable": 99710,
    "traceId": "yt-content-search-abc123",
    "timestamp": 1750732453635,
    "errorCode": "",
    "errorDescription": "",
    "success": true
}

Instagram content search

Method: POST
Endpoint: https://apiv3.creatordb.app/instagram/content-search

Content-level filters

Name	Type	Example	Sortable	Description
`postType`	string	`reel`	No	Content type: `reel`, `slideshow`, or `video`. Single-image posts, multi-image carousels, and many videos are returned as `slideshow`. Also sets the content-type price.
`description`	string or string[]	`skincare routine`	No	The post caption, across all post types. Ignores case and spaces. Supports fuzzy search. Instagram has no separate title filter. Uses the `description` prices.
`hashtag`	string or string[]	`#skincare`	No	A hashtag used in the caption. Ignores case. Supports fuzzy search.
`publishTime`	number	`30`	Yes	Recency in days ago. `< 30` means the last 30 days.
`likes`	number	`5000`	Yes	The number of likes.
`comments`	number	`100`	Yes	The number of comments.
`engagement`	number	`0.05`	Yes	The engagement rate of the content.
`isSponsored`	boolean	`true`	No	`true` if Instagram’s native sponsor-tag metadata is present.
`partneredBrands`	string or string[]	`acer.com`	No	Brand IDs associated with the sponsored content. Ignores case.
`performanceLikes`	number	`1.5`	Yes	Like performance against the creator’s average.
`performanceEngagement`	number	`1.2`	Yes	Engagement performance against the creator’s average.

Creator-level filters

Name	Type	Example	Sortable	Description
`uniqueId`	string or string[]	`goodalicia`	No	The creator’s handle. Use it to search one creator’s content.
`creatorDisplayName`	string or string[]	`alicia`	No	The account display name. Supports fuzzy search.
`creatorBio`	string or string[]	`skincare`	No	The account bio text. Supports fuzzy search.
`country`	string or string[]	`USA`	No	The creator’s country, estimated by CreatorDB’s location model, in ISO 3166-1 alpha-3. For details, see Country Codes.
`creatorLanguage`	string or string[]	`eng`	No	The primary language of the creator’s posts in ISO 639-3. For details, see Language Codes.
`creatorCategory`	string or string[]	`Art`	No	The creator’s professional account category. Ignores case. For details, see Instagram Categories.
`followers`	number	`100000`	Yes	The creator’s follower count, from a daily snapshot. A `>` value of 100,000 or higher uses the 100K+ prices.
`avgEngagement`	number	`0.05`	No	The creator’s average engagement rate.
`contentTopics`	string or string[]	`id_vlog_UniversalTopics_instagram`	No	CreatorDB’s AI-generated content topic.
`contentNiches`	string or string[]	`beauty_Lifestyle`	No	CreatorDB’s AI-generated niche classification.
`audienceLocation`	string or string[]	`USA`	No	The creator’s top audience country in ISO 3166-1 alpha-3. For details, see Country Codes.
`audienceAvgAge`	string or string[]	`18-24`	No	The primary audience age range: `13-17`, `18-24`, `25-34`, `35-44`, `45-54`, `55-64`, or `65+`. Not an average age.
`audienceMaleRatio`	number	`0.6`	No	The proportion of male followers, from 0 to 1.
`audienceFemaleRatio`	number	`0.4`	No	The proportion of female followers, from 0 to 1.
`isVerified`	boolean	`true`	No	`true` if the account is verified by Instagram.

Instagram content search does not expose view counts. Reels and videos return lengthSec, the length in seconds, or null when it isn’t known. Slideshows don’t return lengthSec. You can’t filter or sort on it. Engagement rate is calculated as (likes + comments) / followers for posts and (likes + comments) / plays for reels.The contentType response field can be null on legacy posts that predate post-type classification.

Request example
Response example

Find trending reels with a specific hashtag this week. Reels, 7 days or less, no description, all creators: 1 credit.

curl -X POST "https://apiv3.creatordb.app/instagram/content-search" \
--header 'Content-Type: application/json' \
--header 'api-key: <YOUR_API_KEY_HERE>' \
-d '{
    "filters": [
        { "filterName": "hashtag", "op": "=", "value": "#skincare", "isFuzzySearch": true },
        { "filterName": "postType", "op": "=", "value": "reel" },
        { "filterName": "likes", "op": ">", "value": 5000 },
        { "filterName": "publishTime", "op": "<", "value": 7 }
    ],
    "sortBy": "likes",
    "desc": true,
    "pageSize": 20,
    "offset": 0
}'

Find image and video posts whose caption mentions “gifted”, over a 90-day range, from creators with over 100,000 followers. Posts, 90 days or less, with description, 100K+: 4 credits.

curl -X POST "https://apiv3.creatordb.app/instagram/content-search" \
--header 'Content-Type: application/json' \
--header 'api-key: <YOUR_API_KEY_HERE>' \
-d '{
    "filters": [
        { "filterName": "description", "op": "=", "value": "gifted", "isFuzzySearch": true },
        { "filterName": "postType", "op": "in", "value": ["slideshow", "video"] },
        { "filterName": "followers", "op": ">", "value": 100000 }
    ],
    "timeRange": { "from": 1783036800000, "to": 1790812800000 },
    "sortBy": "likes",
    "desc": true,
    "pageSize": 100,
    "offset": 0
}'

Find sponsored content of any type from creators with large followings. Any type, 30 days or less, no description, 100K+: 1 credit.

curl -X POST "https://apiv3.creatordb.app/instagram/content-search" \
--header 'Content-Type: application/json' \
--header 'api-key: <YOUR_API_KEY_HERE>' \
-d '{
    "filters": [
        { "filterName": "isSponsored", "op": "=", "value": true },
        { "filterName": "followers", "op": ">", "value": 500000 },
        { "filterName": "publishTime", "op": "<", "value": 30 }
    ],
    "sortBy": "engagement",
    "desc": true,
    "pageSize": 20,
    "offset": 0
}'

Response to the first request example:

{
    "data": {
        "contentList": [
            {
                "contentId": "DMCkc5CyZdf",
                "contentType": "reel",
                "description": "突然覺得這輩子一定要好好賺錢\n以後都搭商務艙😭😭😭",
                "thumbnail": "https://www.instagram.com/p/DMCkc5CyZdf/media/?size=l",
                "url": "https://www.instagram.com/reel/DMCkc5CyZdf",
                "publishTime": 1752392905000,
                "isSponsored": false,
                "partneredBrands": [],
                "likes": 15840,
                "comments": 121,
                "engagementRate": 0.1201,
                "hashtags": ["#skincare", "#routine"],
                "creator": {
                    "uniqueId": "goodalicia",
                    "displayName": "愛莉莎莎 Alisasa 🐨",
                    "avatarUrl": "https://instagram.ftpe8-4.fna.fbcdn.net/...",
                    "totalFollowers": 613344
                }
            }
        ],
        "totalResults": 850,
        "hasNextPage": true,
        "nextOffset": 20,
        "timeRange": {
            "from": 1750127653635,
            "to": 1750732453635,
            "isDefault": false
        }
    },
    "creditsUsed": 1,
    "creditsAvailable": 99758,
    "traceId": "ig-content-search-abc123",
    "timestamp": 1750732453635,
    "errorCode": "",
    "errorDescription": "",
    "success": true
}

Slideshow post URLs follow the pattern https://www.instagram.com/p/{contentId}, and reel URLs follow https://www.instagram.com/reel/{contentId}.

TikTok content search

Method: POST
Endpoint: https://apiv3.creatordb.app/tiktok/content-search

TikTok sponsored-content detection is not built. The isSponsored and partneredBrands filters and response fields are not available on this endpoint.TikTok’s isAd field on /tiktok/content-detail is not CreatorDB’s sponsored-content signal. It is TikTok’s own platform-level ad-disclosure flag, and it cannot be used as a filter here.

Content-level filters

Name	Type	Example	Sortable	Description
`description`	string or string[]	`fyp tutorial`	No	The video caption. Ignores case and spaces. Supports fuzzy search. Uses the `description` prices.
`hashtag`	string or string[]	`#foryoupage`	No	A hashtag used in the description. Ignores case. Supports fuzzy search.
`publishTime`	number	`30`	Yes	Recency in days ago. `< 30` means the last 30 days.
`plays`	number	`1000000`	Yes	The number of plays. `plays` is TikTok’s term for views.
`diggs`	number	`50000`	Yes	The number of likes. `diggs` is TikTok’s term for likes.
`comments`	number	`1000`	Yes	The number of comments.
`shares`	number	`500`	Yes	The number of shares.
`engagement`	number	`0.05`	Yes	The engagement rate of the video.
`lengthSec`	number	`60`	Yes	The video duration in seconds.
`performanceDiggs`	number	`1.5`	Yes	Like performance against the creator’s average.
`performanceEngagement`	number	`1.2`	Yes	Engagement performance against the creator’s average.

Creator-level filters

Name	Type	Example	Sortable	Description
`uniqueId`	string or string[]	`khaby.lame`	No	The creator’s handle. Use it to search one creator’s content.
`creatorDisplayName`	string or string[]	`aesthetic`	No	The account display name. Supports fuzzy search.
`creatorBio`	string or string[]	`dance`	No	The account bio text. Supports fuzzy search.
`country`	string or string[]	`USA`	No	The creator’s country in ISO 3166-1 alpha-3. For details, see Country Codes.
`creatorLanguage`	string or string[]	`eng`	No	The primary language of the creator’s posts in ISO 639-3. For details, see Language Codes.
`creatorCategory`	string or string[]	`Entertainment`	No	The creator’s account category. Ignores case.
`followers`	number	`100000`	Yes	The creator’s follower count, from a daily snapshot. A `>` value of 100,000 or higher uses the 100K+ prices.
`avgEngagement`	number	`0.05`	No	The creator’s average engagement rate.
`contentTopics`	string or string[]	`id_socialmedia_Entertainment_tiktok`	No	CreatorDB’s AI-generated content topic.
`contentNiches`	string or string[]	`dance_Entertainment`	No	CreatorDB’s AI-generated niche classification.
`audienceLocation`	string or string[]	`USA`	No	The creator’s top audience country in ISO 3166-1 alpha-3. For details, see Country Codes.
`audienceAvgAge`	string or string[]	`18-24`	No	The primary audience age range: `13-17`, `18-24`, `25-34`, `35-44`, `45-54`, `55-64`, or `65+`. Not an average age.
`audienceMaleRatio`	number	`0.6`	No	The proportion of male followers, from 0 to 1.
`audienceFemaleRatio`	number	`0.4`	No	The proportion of female followers, from 0 to 1.
`isVerified`	boolean	`true`	No	`true` if the account is verified by TikTok.

Likes are called diggs when you filter and likes when you read. The filter uses TikTok’s native diggs terminology, while the response normalizes the field to likes for consistency with the other platforms. Plays use plays in both places.TikTok engagement rate is calculated as (likes + comments + shares) / plays. The shares component is unique to TikTok.Results include audioTitle and audioAuthor, which are useful for tracking trending sounds. Audio is returned but is not currently filterable.

Request example
Response example

Find viral videos from the last 7 days. 7 days or less, no description, all creators: 1 credit.

curl -X POST "https://apiv3.creatordb.app/tiktok/content-search" \
--header 'Content-Type: application/json' \
--header 'api-key: <YOUR_API_KEY_HERE>' \
-d '{
    "filters": [
        { "filterName": "plays", "op": ">", "value": 5000000 },
        { "filterName": "publishTime", "op": "<", "value": 7 },
        { "filterName": "engagement", "op": ">", "value": 0.05 }
    ],
    "sortBy": "plays",
    "desc": true,
    "pageSize": 20,
    "offset": 0
}'

Find US videos whose caption mentions “skincare routine” over the past year. 365 days or less, with description, all creators: 17 credits. Adding { "filterName": "followers", "op": ">", "value": 100000 } brings the same search down to 4 credits.

curl -X POST "https://apiv3.creatordb.app/tiktok/content-search" \
--header 'Content-Type: application/json' \
--header 'api-key: <YOUR_API_KEY_HERE>' \
-d '{
    "filters": [
        { "filterName": "description", "op": "=", "value": "skincare routine", "isFuzzySearch": true },
        { "filterName": "country", "op": "=", "value": "USA" }
    ],
    "timeRange": { "from": 1759276800000, "to": 1790812800000 },
    "sortBy": "plays",
    "desc": true,
    "pageSize": 100,
    "offset": 0
}'

Find content with a trending hashtag from larger creators in a specific market. 30 days or less (14 days), no description, 100K+: 1 credit.

curl -X POST "https://apiv3.creatordb.app/tiktok/content-search" \
--header 'Content-Type: application/json' \
--header 'api-key: <YOUR_API_KEY_HERE>' \
-d '{
    "filters": [
        { "filterName": "hashtag", "op": "=", "value": "#foryoupage" },
        { "filterName": "country", "op": "=", "value": "USA" },
        { "filterName": "followers", "op": ">", "value": 100000 },
        { "filterName": "publishTime", "op": "<", "value": 14 }
    ],
    "sortBy": "shares",
    "desc": true,
    "pageSize": 20,
    "offset": 0
}'

Response to the second request example. The response echoes the requested window in data.timeRange.

{
    "data": {
        "contentList": [
            {
                "contentId": "7318379374288424225",
                "description": "my night skincare routine ✨🤍 #skincare #foryoupage",
                "thumbnail": "https://p19-common-sign-useastred.tiktokcdn-eu.com/...",
                "url": "https://www.tiktok.com/@.....aaaaesthetic/video/7318379374288424225",
                "publishTime": 1789561394000,
                "lengthSec": 11,
                "plays": 1947,
                "likes": 239,
                "comments": 7,
                "shares": 1,
                "engagementRate": 0.1269,
                "hashtags": ["#skincare", "#foryoupage"],
                "audioTitle": "original sound - User",
                "audioAuthor": "User",
                "creator": {
                    "uniqueId": ".....aaaaesthetic",
                    "displayName": ".....aaesthetic",
                    "avatarUrl": "https://p16-sign-va.tiktokcdn.com/...",
                    "totalFollowers": 38100
                }
            }
        ],
        "totalResults": 3200,
        "hasNextPage": true,
        "nextOffset": 100,
        "timeRange": {
            "from": 1759276800000,
            "to": 1790812800000,
            "isDefault": false
        }
    },
    "creditsUsed": 17,
    "creditsAvailable": 99758,
    "traceId": "tt-content-search-abc123",
    "timestamp": 1790812800000,
    "errorCode": "",
    "errorDescription": "",
    "success": true
}

Video URLs follow the pattern https://www.tiktok.com/@{uniqueId}/video/{contentId}.

Paginating results

Send offset: 0 on your first call. If the response has hasNextPage: true, send the returned nextOffset as the offset of your next request, keeping every other parameter the same. For example, the second request for a query that returns 100 results per page:

{
    "filters": [
        { "filterName": "views", "op": ">", "value": 1000000 },
        { "filterName": "publishTime", "op": "<", "value": 30 }
    ],
    "sortBy": "views",
    "desc": true,
    "pageSize": 100,
    "offset": 100
}

Every page is a new search and bills the full price again. On YouTube, paging through 10 pages of this 3-credit query costs 30 credits. Use the largest pageSize you can (up to 100) so that you make as few calls as possible. Check totalResults on your first call to see how deep the result set goes before you commit to paging through it, but keep in mind that totalResults can count items that contentList doesn’t return.If you page with timeRange, keep sending the same from and to. Leaving out to lets the window grow with each call, which can move a request into the next price tier.

Common errors

Invalid requests return 400 VALIDATION_ERROR and aren’t billed. The details array names each field that failed and why.

{
    "success": false,
    "error": "ValidationError",
    "message": "Request validation failed",
    "errorCode": "VALIDATION_ERROR",
    "traceId": "abc-123",
    "timestamp": 1790812800000,
    "details": [
        {
            "field": "filters.0.isFuzzySearch",
            "message": "isFuzzySearch is not supported for field 'country'. Allowed fields: description, hashtag, creatorDisplayName, creatorBio"
        }
    ]
}

Cause	`details[].field`	`details[].message`	Fix
`isFuzzySearch` on a filter that isn’t free text, such as `country`	`filters.<i>.isFuzzySearch`	`isFuzzySearch is not supported for field '...'. Allowed fields: ...`	Remove `isFuzzySearch`, or use a free-text filter. See Matching text.
`isFuzzySearch` on a number field, such as `plays`	`filters.<i>.isFuzzySearch`	`isFuzzySearch can only be used with string-type fields`	Remove `isFuzzySearch`.
A fuzzy `in` with more than 10 values	`filters.<i>.value`	`isFuzzySearch with op "in" accepts at most 10 values`	Split the values across several requests.
`timeRange` and `publishTime` don’t overlap	`timeRange`, plus `filters.<i>.value` for each `publishTime` filter	`timeRange does not overlap the publishTime filter`	Widen `timeRange` or change the `publishTime` filter.
`publishTime` filters that exclude each other, such as `< 7` and `> 30`	`filters.<i>.value` for each `publishTime` filter	`publishTime filters leave no time window`	Remove one of the filters.
`timeRange` values in seconds instead of milliseconds	`timeRange.from` or `timeRange.to`	`must be a Unix timestamp in milliseconds, not seconds (min 1000000000000)`	Multiply by 1000.
`from` is the same as or later than `to`	`timeRange.from`	`from must be earlier than to (to defaults to the time of the request)`	Check the order, and that `from` isn’t in the future when you leave out `to`.
A `postType` value the platform doesn’t accept, such as `shorts` on Instagram	`filters.<i>.value`	`Invalid value for postType. Must be one of: ...`	Use a value from Post types differ per platform.
A timestamp in `publishTime`	`filters.<i>.value`	`publishTime is a number of days ago (max 36500), not a Unix timestamp`	Send days, or use `timeRange` for absolute dates.

For all error codes and the response envelope, see Error Codes.

Platform differences at a glance

	YouTube	Instagram	TikTok
Content types	`video`, `shorts`, `stream`	`slideshow`, `reel`, `video`	Videos only
Content-type pricing	Any type, Shorts, Long videos	Any type, Reels, Posts	None
`description` searches	Video description	Caption	Caption
View metric	`views`	Not available	`plays`
Content length	`lengthSec`	`lengthSec` on reels and videos (not filterable)	`lengthSec`
Shares	Not available	Not available	`shares`
Sponsored filtering	Yes, CreatorDB AI model	Yes, native sponsor tags	No, detection is not built
Title filter	Yes, separate from `description`	No, `description` searches the caption	No, `description` searches the caption
Creator ID filter	`channelId`	`uniqueId`	`uniqueId`
Topic classification	`contentTopics` and `contentNiches`	`contentTopics` and `contentNiches`	`contentTopics` and `contentNiches`
Audio metadata	No	No	Yes, returned but not filterable
Engagement rate	(likes + comments) / views	Posts: (likes + comments) / followers Reels: (likes + comments) / plays	(likes + comments + shares) / plays

Troubleshooting

For error codes and the response envelope, see Error Codes. Besides the common errors above, the most common content-search mistakes are:

Paying more than expected. Check the four price inputs in Credit cost. A window longer than 30 days, or one with no start such as publishTime > 30 on its own, is priced in a higher tier.
Missing older content. A request with no timeRange and no publishTime filter only searches the last 30 days. Check data.timeRange.isDefault, and set timeRange to search further back.
Getting no results from a description search. Set isFuzzySearch to true. Without it, the value must match the whole caption or description. To match any of several phrases, use in with isFuzzySearch: true.
Passing an average age to audienceAvgAge. The filter takes an age-range string, such as 18-24.
Sorting on a field that is not sortable. Check the Sortable column in the tables above.
Using a brand name in partneredBrands. Use the brand ID, typically a domain such as acer.com.
Sending an empty filters array or an empty in array. Include at least one filter, and at least one value in every in array.
Sending more than 10 filters or an in array longer than 100 values. For the limits, see Request parameters.
Filtering on isSponsored for TikTok. TikTok sponsored-content detection is not built.

Getting Started

User Guides

API Endpoints

Filter Value References

Troubleshooting and FAQs

Overview

Before you start

How content search works

Request parameters

Searching a time window

The effective window

The applied window in the response

Two kinds of filters

Matching text

Searching one creator’s content

Filter behavior to know before you start

Credit cost

What sets the price

Prices by platform

Working out a price

How to lower the cost

What you get back

Filter names and response field names

Content search by platform

YouTube content search

Content-level filters

Creator-level filters

Instagram content search

Content-level filters

Creator-level filters

TikTok content search

Content-level filters

Creator-level filters

Paginating results

Common errors

Platform differences at a glance

Troubleshooting

​Overview

​Before you start

​How content search works

​Request parameters

​Searching a time window

​The effective window

​The applied window in the response

​Two kinds of filters

​Matching text

​Searching one creator’s content

​Filter behavior to know before you start

​Credit cost

​What sets the price

​Prices by platform

​Working out a price

​How to lower the cost

​Empty results and pagination

​What you get back

​Filter names and response field names

​Content search by platform

​YouTube content search

​Content-level filters

​Creator-level filters

​Instagram content search

​Content-level filters

​Creator-level filters

​TikTok content search

​Content-level filters

​Creator-level filters

​Paginating results

​Common errors

​Platform differences at a glance

​Troubleshooting

Overview

Before you start

How content search works

Request parameters

Searching a time window

The effective window

The applied window in the response

Two kinds of filters

Matching text

Searching one creator’s content

Filter behavior to know before you start

Credit cost

What sets the price

Prices by platform

Working out a price

How to lower the cost

Empty results and pagination

What you get back

Filter names and response field names

Content search by platform

YouTube content search

Content-level filters

Creator-level filters

Instagram content search

Content-level filters

Creator-level filters

TikTok content search

Content-level filters

Creator-level filters

Paginating results

Common errors

Platform differences at a glance

Troubleshooting