> ## Documentation Index > Fetch the complete documentation index at: https://docs.creatordb.app/llms.txt > Use this file to discover all available pages before exploring further. # Using Content Search > Search for specific videos, posts, and reels across every creator in the CreatorDB database ## 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](/api-v3/configuring_advanced_search_filters). 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](/api-v3/authentication). * Check your credit balance. **Content search costs significantly more per call than creator search** because each query scans every piece of content in the database rather than one creator's recent posts. Read [Credit cost](#credit-cost) before your first call. * 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: ```http theme={null} 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. ### 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[]`. Using `=` on a string field takes a `string`. | | `filters[].isFuzzySearch` | boolean | No | Set to `true` to match a string field on a substring instead of an exact value. Only available on string fields. | | `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. | **Important: Request parameter limits** * **Filter count**: Maximum of **10** filter objects per request. * **Array value limit**: When using the `in` operator, the array can contain a maximum of **100** string values. * **Page size**: The upper limit for `pageSize` is **100**. * **Fuzzy search**: `isFuzzySearch: true` is only available on **string** fields. ## 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. ## Filter behavior to know before you start Five filters behave differently from what their names suggest. Read these 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 }`. The `publishTime` **field in the response** is a Unix timestamp in milliseconds. The filter and the response field use different units. ### 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 | An AI model classifies the content as sponsored, combined with brand ID mapping. | | Instagram | Relies on the presence of Instagram's native sponsor-tag metadata. This matches the definition used by `/instagram/content-detail` and `/instagram/sponsorship`, so a post is consistently sponsored or not across all three endpoints. | | TikTok | **Not available yet.** As a result, `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. | Platform | Accepted `postType` values | | :-------- | :--------------------------- | | YouTube | `video`, `shorts`, `stream` | | Instagram | `slideshow`, `reel`, `video` | | TikTok | Not applicable | On Instagram, both single-image posts and multi-image carousels are returned as `slideshow`. The `postType` value alone can't tell them apart; to distinguish them, check the length of the carousel media array in the response. ## Credit cost Content search is priced per call, and the price does not depend on the number of results returned. Every page of a paginated result set is a fresh search and bills at the full rate. There is no discount after the first page. | Endpoint | Credits per call | | :------------------------- | :------------------------------------- | | `instagram/content-search` | 10 | | `tiktok/content-search` | 2 | | `youtube/content-search` | 50, or 100 with a `description` filter | On YouTube, including a `description` filter in any request doubles the cost of that call from **50 to 100 credits**. The tier is set by whether *any* filter targets `description`, not by the number of filters you send. Searching video descriptions is more expensive than scanning other text fields. If you only need to match the title text, use the `title` filter instead to stay on the 50-credit tier. For all endpoint pricing, see [API Credit Usage](/api-v3/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 total 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. | 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. 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. ## Content search by platform ## 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`. | | `title` | string or string\[] | `"minecraft tutorial"` | No | The video title. Supports fuzzy search. | | `description` | string or string\[] | `"sponsored by"` | No | The video description. Supports fuzzy search. **Triggers the 100-credit tier.** | | `hashtag` | string or string\[] | `#gaming` | No | A hashtag used in the video title or description. Case-insensitive. | | `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 content engagement rate. | | `isSponsored` | boolean | `true` | No | Is `true` if sponsored. | | `partneredBrands` | string or string\[] | `acer.com` | No | Brand IDs of content sponsors. | | `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](/api-v3/language-code). | | `category` | string or string\[] | `Gaming` | No | The YouTube-defined content category. For details, see [YouTube Channel Categories](/api-v3/youtube-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 | | :-------------------- | :------------------ | :-------------------- | :------- | :----------------------------------------------------------------------------------------------------------------- | | `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 Code](/api-v3/country-code). | | `creatorLanguage` | string or string\[] | `eng` | No | The channel's main language in ISO 639-3. For details, see [Language Codes](/api-v3/language-code). | | `creatorCategory` | string or string\[] | `Gaming` | No | The creator's primary content category. For details, see [YouTube Channel Categories](/api-v3/youtube-categories). | | `followers` | number | `1000000` | Yes | The creator's total subscriber count. | | `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 Code](/api-v3/country-code). | | `audienceAvgAge` | string | `18-24` | No | The primary audience age range: `13-17`, `18-24`, `25-34`, `35-44`, `45-54`, `55-64`, or `65+`. | | `audienceMaleRatio` | number | `0.6` | No | The proportion of male subscribers. | | `audienceFemaleRatio` | number | `0.4` | No | The proportion of female subscribers. | | `isVerified` | boolean | `true` | No | Is `true` if the account is verified by YouTube. | YouTube engagement rate is calculated as *(likes + comments + views) / subscribers*, and the response rounds `engagementRate` to four decimal places. Find high-performing sponsored videos from the last 30 days: ```bash theme={null} curl -X POST "https://apiv3.creatordb.app/youtube/content-search" \ --header 'Content-Type: application/json' \ --header 'api-key: YOUR_API_KEY' \ -d '{ "filters": [ { "filterName": "isSponsored", "op": "=", "value": true }, { "filterName": "views", "op": ">", "value": 1000000 }, { "filterName": "publishTime", "op": "<", "value": 30 }, { "filterName": "postType", "op": "=", "value": "video" } ], "sortBy": "views", "desc": true, "pageSize": 20, "offset": 0 }' ``` Find every video sponsored by a specific brand in the last 90 days: ```bash theme={null} curl -X POST "https://apiv3.creatordb.app/youtube/content-search" \ --header 'Content-Type: application/json' \ --header 'api-key: YOUR_API_KEY' \ -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, from creators reaching a specific audience: ```bash theme={null} curl -X POST "https://apiv3.creatordb.app/youtube/content-search" \ --header 'Content-Type: application/json' \ --header 'api-key: YOUR_API_KEY' \ -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 }' ``` ```json theme={null} { "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 }, "creditsUsed": 50, "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 | Accepted `postType` values: `slideshow`, `reel`, or `video`. Single images are returned as `slideshow`. | | `description` | string or string\[] | `"skincare routine"` | No | The post text. Searches the caption on all post types, plus the title on reels that have one, as a single combined field. Supports fuzzy search. | | `hashtag` | string or string\[] | `#skincare` | No | A hashtag used in the caption. Case-insensitive. | | `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 content engagement rate. | | `isSponsored` | boolean | `true` | No | Is `true` if the content has the Instagram-native sponsor tag. | | `partneredBrands` | string or string\[] | `acer.com` | No | Brand IDs of content sponsors. | | `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 | | :-------------------- | :------------------ | :----------------- | :------- | :------------------------------------------------------------------------------------------------------------------ | | `creatorDisplayName` | string or string\[] | `"alicia"` | No | The account display name. Supports fuzzy search. | | `creatorBio` | string or string\[] | `"skincare"` | No | The account 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 Code](/api-v3/country-code). | | `creatorLanguage` | string or string\[] | `eng` | No | The main language of the creator's posts in ISO 639-3. For details, see [Language Code](/api-v3/language-code). | | `creatorCategory` | string or string\[] | `Art` | No | The creator's professional account category. For details, see [Instagram Categories](/api-v3/instagram-categories). | | `followers` | number | `100000` | Yes | The creator's total follower count. | | `avgEngagement` | number | `0.05` | No | The creator's average engagement rate. | | `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 Code](/api-v3/country-code). | | `audienceAvgAge` | string | `18-24` | No | The primary audience age range: `13-17`, `18-24`, `25-34`, `35-44`, `45-54`, `55-64`, or `65+`. | | `audienceMaleRatio` | number | `0.6` | No | The proportion of male followers. | | `audienceFemaleRatio` | number | `0.4` | No | The proportion of female followers. | | `isVerified` | boolean | `true` | No | Is `true` if the account is verified. | Instagram content search does not expose view counts or content length, because Instagram's data model does not reliably provide either at the post level. Engagement rate is calculated as *(likes + comments) / followers*. The `contentType` response field can be `null` on legacy posts that predate post-type classification. Find trending reels with a specific hashtag: ```bash theme={null} curl -X POST "https://apiv3.creatordb.app/instagram/content-search" \ --header 'Content-Type: application/json' \ --header 'api-key: YOUR_API_KEY' \ -d '{ "filters": [ { "filterName": "hashtag", "op": "=", "value": "#skincare" }, { "filterName": "postType", "op": "=", "value": "reel" }, { "filterName": "likes", "op": ">", "value": 5000 }, { "filterName": "publishTime", "op": "<", "value": 7 } ], "sortBy": "likes", "desc": true, "pageSize": 20, "offset": 0 }' ``` Find sponsored content from creators with large followings: ```bash theme={null} curl -X POST "https://apiv3.creatordb.app/instagram/content-search" \ --header 'Content-Type: application/json' \ --header 'api-key: YOUR_API_KEY' \ -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 }' ``` Find high-engagement image posts in a specific country: ```bash theme={null} curl -X POST "https://apiv3.creatordb.app/instagram/content-search" \ --header 'Content-Type: application/json' \ --header 'api-key: YOUR_API_KEY' \ -d '{ "filters": [ { "filterName": "postType", "op": "=", "value": "slideshow" }, { "filterName": "country", "op": "=", "value": "USA" }, { "filterName": "engagement", "op": ">", "value": 0.1 }, { "filterName": "publishTime", "op": "<", "value": 14 } ], "sortBy": "likes", "desc": true, "pageSize": 20, "offset": 0 }' ``` ```json theme={null} { "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 }, "creditsUsed": 10, "creditsAvailable": 99758, "traceId": "ig-content-search-abc123", "timestamp": 1750732453635, "errorCode": "", "errorDescription": "", "success": true } ``` Image 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` Sponsored-content detection for TikTok is not yet implemented. The `isSponsored` and `partneredBrands` filters and response fields are not available on this endpoint. TikTok's native `isAd` flag is exposed per video on `/tiktok/content-detail`, but it does not carry the same meaning as CreatorDB's sponsored-content definition and 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. Supports fuzzy search. | | `hashtag` | string or string\[] | `#foryoupage` | No | A hashtag used in the description. Case-insensitive. | | `publishTime` | number | `30` | Yes | Recency in days ago. `< 30` means the last 30 days. | | `plays` | number | `1000000` | Yes | The number of plays. TikTok's term for views. | | `diggs` | number | `50000` | Yes | The number of likes. 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 | | :-------------------- | :------------------ | :-------------------- | :------- | :---------------------------------------------------------------------------------------------- | | `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. | | `creatorLanguage` | string or string\[] | `eng` | No | The main language of the creator's posts, in ISO 639-3. | | `creatorCategory` | string or string\[] | `Entertainment` | No | The creator's account category. | | `followers` | number | `100000` | Yes | The creator's total follower count. | | `avgEngagement` | number | `0.05` | No | The creator's average engagement rate. | | `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. | | `audienceAvgAge` | string | `18-24` | No | The primary audience age range: `13-17`, `18-24`, `25-34`, `35-44`, `45-54`, `55-64`, or `65+`. | | `audienceMaleRatio` | number | `0.6` | No | The proportion of male followers. | | `audienceFemaleRatio` | number | `0.4` | No | The proportion of female followers. | | `isVerified` | boolean | `true` | No | Whether the account is verified. | **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. The same applies to plays: filter on `plays`, and read `plays` in the response. TikTok engagement rate is calculated as *(likes + comments + shares) / followers*. The `shares` component is unique to TikTok. Results include `audioTitle` and `audioAuthor`, which is useful for tracking trending sounds. Audio is returned but is not currently filterable. Find viral videos from the last 7 days: ```bash theme={null} curl -X POST "https://apiv3.creatordb.app/tiktok/content-search" \ --header 'Content-Type: application/json' \ --header 'api-key: YOUR_API_KEY' \ -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 content with a trending hashtag from creators in a specific market: ```bash theme={null} curl -X POST "https://apiv3.creatordb.app/tiktok/content-search" \ --header 'Content-Type: application/json' \ --header 'api-key: YOUR_API_KEY' \ -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 }' ``` Find highly shared short-form content: ```bash theme={null} curl -X POST "https://apiv3.creatordb.app/tiktok/content-search" \ --header 'Content-Type: application/json' \ --header 'api-key: YOUR_API_KEY' \ -d '{ "filters": [ { "filterName": "shares", "op": ">", "value": 10000 }, { "filterName": "lengthSec", "op": "<", "value": 30 }, { "filterName": "publishTime", "op": "<", "value": 30 } ], "sortBy": "shares", "desc": true, "pageSize": 20, "offset": 0 }' ``` ```json theme={null} { "data": { "contentList": [ { "contentId": "7318379374288424225", "description": "hope everyone is having a nice day! ✨🤍 #xmas #foryoupage", "thumbnail": "https://p19-common-sign-useastred.tiktokcdn-eu.com/...", "url": "https://www.tiktok.com/@.....aaaaesthetic/video/7318379374288424225", "publishTime": 1703942994000, "lengthSec": 11, "plays": 1947, "likes": 239, "comments": 7, "shares": 1, "engagementRate": 0.1269, "hashtags": ["#xmas", "#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": 20 }, "creditsUsed": 2, "creditsAvailable": 99758, "traceId": "tt-content-search-abc123", "timestamp": 1750732453635, "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. ```json theme={null} { "filters": [ { "filterName": "views", "op": ">", "value": 1000000 } ], "sortBy": "views", "desc": true, "pageSize": 100, "offset": 100 } ``` Every page bills at the full per-call rate. Paginating through 10 pages of YouTube results costs 500 credits, not 50. Use the largest `pageSize` you can (up to 100) so that you make as few calls as possible, and check `totalResults` on your first call to see how deep the result set goes before you commit to paging through it. ## Platform differences at a glance | | YouTube | Instagram | TikTok | | :------------------- | :--------------------------------------- | :-------------------------------------------------------------------------- | :-------------------------------------- | | Credits per call | 50, or 100 with `description` | 10 | 2 | | Content types | `video`, `shorts`, `stream` | `slideshow`, `reel`, `video` | Videos only | | View metric | `views` | Not available | `plays` | | Content length | `lengthSec` | Not available | `lengthSec` | | Shares | Not available | Not available | `shares` | | Sponsored filtering | Yes, AI-classified | Yes, native sponsor tags | Not implemented | | Title filter | Yes, separate from `description` | Folded into `description`, which searches captions and reel titles together | No, captions only via `description` | | Topic classification | `contentTopics` and `contentNiches` | `contentNiches` | `contentNiches` | | Audio metadata | No | No | Yes, returned but not filterable | | Engagement rate | (likes + comments + views) / subscribers | (likes + comments) / followers | (likes + comments + shares) / followers | ## Troubleshooting For error codes and the response envelope, see [Error Codes](/api-v3/error-code). The most common content-search mistakes are: * **Passing a timestamp to `publishTime`.** The filter takes a number of days ago. * **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 more than 10 filters**, or an `in` array longer than 100 values. * **Filtering on `isSponsored` for TikTok.** It is not implemented on that platform.