> ## 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.
# Search Creators
> Search for YouTube creators using advanced filters such as `displayName`, subscriber count, video performance, and more. Supports fuzzy search, pagination, and multiple filter combinations with up to 10 filters per request. By default the `creatorList` is sorted by `displayName`. Custom sorting can be applied using the `sortBy` parameter.
Optionally pass `fields` to enrich each search result with data from other endpoints. Enrichment is billed per result returned, using each endpoint's own pricing rules. Fractional calls must be enabled on your API key. For details, see [Fractional Calls](/api-v3/fractional-calls).
## OpenAPI
````yaml /api-v3/api-v3.yaml post /youtube/search
openapi: 3.1.0
info:
version: 1.0.0
title: CreatorDB Headless API V3
description: '# CreatorDB Headless API V3'
contact:
name: CreatorDB
url: https://www.creatordb.app
email: support@creatordb.app
license:
url: http://www.apache.org/licenses/LICENSE-2.0.html
name: Apache 2.0
servers:
- url: https://apiv3.creatordb.app
description: Production Environment (CreatorDB Headless API V3)
security:
- ApiKeyAuth: []
tags:
- name: Brand
description: Brand analysis endpoints including sponsor search and brand reports.
- name: Facebook
description: Facebook creator data endpoints with metrics and search capabilities.
- name: General Operations
description: >-
General-purpose endpoints such as API status, content retrieval, and
cross-platform operations.
- name: Instagram
description: >-
Instagram creator data endpoints with metrics and advanced search
capabilities.
- name: Niches
description: >-
Niche-related endpoints for content category analysis and related
searches.
- name: Threads
description: Threads creator data endpoints with basic metrics and historical data.
- name: TikTok
description: >-
TikTok creator data endpoints with metrics and advanced search
functionality.
- name: Topic
description: Topic-based analysis and reporting endpoints for content categorization.
- name: YouTube
description: >-
YouTube creator data endpoints including basic metrics, historical data,
and detailed analytics.
paths:
/youtube/search:
post:
tags:
- YouTube
summary: Search Creators
description: >-
Search for YouTube creators using advanced filters such as
`displayName`, subscriber count, video performance, and more. Supports
fuzzy search, pagination, and multiple filter combinations with up to 10
filters per request. By default the `creatorList` is sorted by
`displayName`. Custom sorting can be applied using the `sortBy`
parameter.
Optionally pass `fields` to enrich each search
result with data from other endpoints. Enrichment is billed per result
returned, using each endpoint's own pricing rules. Fractional calls must
be enabled on your API key. For details, see [Fractional
Calls](/api-v3/fractional-calls).
operationId: searchYoutube
requestBody:
content:
application/json:
schema:
type: object
description: YouTube search request parameters.
properties:
filters:
type: array
description: >-
Filter objects that include `filterName`, `op`, and `value`.
For all accepted `filterName` values and their data types,
see [Configuring Custom Search Filters and
Examples](https://docs.creatordb.app/api-v3/configuring_advanced_search_filters#available-filtername-&-sortby).
maxItems: 10
items:
type: object
properties:
filterName:
type: string
description: The field to apply the filter on.
op:
type: string
enum:
- in
- '>'
- '='
- <
description: >-
The comparison operator. Accepted values include:
`in`, `>`, `=`, `<`.
- String fields accept:
`=`, `in`.
- Number fields accept: `>`, `=`,
`<`.
- Boolean fields accept: `=`
value:
description: >-
Type depends on the `filterName`.
- String
fields accept `string` or `string[]`.
- Number
fields accept `number`.
- Boolean fields accept
`boolean`.
- Operator `in` accepts `string[]`,
operator `=` accepts string for `string` fields.
anyOf:
- type: string
- type: number
- type: array
maxItems: 100
items:
type: string
- type: boolean
isFuzzySearch:
type: boolean
description: >-
When `true`, performs a fuzzy match for `string` type
`filterName`.
default: false
required:
- filterName
- op
- value
desc:
type: boolean
description: >-
Sort order for results. `true` for descending, `false` for
ascending order.
sortBy:
type: string
description: >-
Field to sort creators by. For example, `totalSubscribers`
sorts by subscriber count.
pageSize:
type: integer
description: 'Number of results per page. Maximum: 100.'
minimum: 1
maximum: 100
offset:
type: integer
description: Number of records to skip before returning results.
minimum: 0
fields:
type: object
description: >-
Enrich each search result with data from other endpoints on
the same platform (e.g. `profile`, `contact`). Enrichment is
billed per result returned, using each endpoint's pricing
rules. Each key is a bare endpoint name, and each key's
value follows that endpoint's fractional shape. Per-field
costs are not published yet.
properties:
profile:
type: array
items:
type: string
description: Profile fields to add to each search result.
performance:
type: array
items:
type: string
description: Performance blocks to add to each search result.
audience:
type: array
items:
type: string
description: Audience fields to add to each search result.
contact:
type: array
items:
type: string
description: Contact fields to add to each search result.
content-detail:
type: object
description: >-
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](/api-v3/fractional-calls).
performance-history:
type: object
required:
- pastDayRange
properties:
pastDayRange:
type: string
pattern: ^[1-9]\d*$
description: >-
Date range bucket, e.g. `{ "pastDayRange": 90 }`. For
pricing, see [Performance history
pricing](/api-v3/api-credit-usage#performance-history-pricing).
sponsorship:
type: object
description: >-
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](/api-v3/fractional-calls).
additionalProperties: false
examples:
- profile:
- country
content-detail:
recentVideos: 3
performance-history:
pastDayRange: 90
sponsorship:
sponsorList: 5
required:
- filters
- pageSize
- offset
examples:
- filters:
- filterName: displayName
op: '='
value: beast
isFuzzySearch: true
desc: true
sortBy: displayName
pageSize: 10
offset: 0
examples:
default:
value:
filters:
- filterName: totalSubscribers
op: '>'
value: 1000000
isFuzzySearch: true
desc: true
sortBy: displayName
pageSize: 10
offset: 0
responses:
'200':
description: YouTube search results returned successfully.
content:
application/json:
schema:
type: object
properties:
data:
type: object
description: >-
Search results containing YouTube creators and pagination
information.
properties:
creatorList:
type: array
description: Creator objects matching the search query.
items:
type: object
description: Creator details in search results.
properties:
displayName:
type: string
description: Channel display name.
examples:
- YouTube
uniqueId:
type: string
description: Unique handle.
examples:
- '@youtube'
channelId:
type: string
description: Unique channel ID.
examples:
- UCBR8-60-B28hp2BmDPdntcQ
avatarUrl:
type: string
description: Channel profile picture URL.
examples:
- >-
https://yt3.googleusercontent.com/7cF22TRiceqQr2Cro_X4uhRVnwCdOa2HXiwdBGPnUEqJDuCyr2CykDfDw2rCWjbjaHEdTMUC=s900-c-k-c0x00ffffff-no-rj
totalSubscribers:
type: integer
description: Total number of subscribers.
minimum: 0
examples:
- 13900000
required:
- displayName
- uniqueId
- channelId
- avatarUrl
- totalSubscribers
hasNextPage:
type: boolean
description: '`true` if there is a next page of results.'
examples:
- true
nextOffset:
type: integer
description: >-
The offset value for retrieving the next page of
results.
minimum: 0
examples:
- 100
required:
- creatorList
- hasNextPage
- nextOffset
creditsUsed:
type: integer
description: Number of API credits consumed by this request.
examples:
- 1
creditsAvailable:
type: integer
description: Number of API credits remaining.
examples:
- -1
traceId:
type: string
description: Unique trace ID for each request.
examples:
- f8e4a3b2c1d0e9f8a7b6c5d4e3f2a1b0
timestamp:
type: integer
description: >-
Time the response was generated, represented as a Unix
timestamp in milliseconds.
examples:
- 1750732453635
errorCode:
type: string
description: >-
Error code returned if the request fails. Empty if the
request is successful.
examples:
- ''
errorDescription:
type: string
description: >-
Description of the error. Empty if the request is
successful.
examples:
- ''
success:
type: boolean
description: '`true` if the request is successful.'
examples:
- true
required:
- data
- traceId
- timestamp
- errorCode
- errorDescription
- success
- creditsUsed
- creditsAvailable
examples:
default:
value:
data:
creatorList:
- displayName: 🪐🌍Gallivud_prod
uniqueId: '@gallivud_prod'
channelId: UCMS8ONu5i0tKTyZ4_lLD1DA
avatarUrl: >-
https://yt3.googleusercontent.com/geeG3ok-_7PzCBlXDEW8Ro2m0QNl_XRH4AekEVvPqBhgmrFJbn2iKzn06lSnI2GnkybvaJY7=s900-c-k-c0x00ffffff-no-rj
totalSubscribers: 1400000
- displayName: 🪐MILENA MARS🪐
uniqueId: '@milenamars'
channelId: UCjTWFYn4s7fzsonX3Jtw_Ig
avatarUrl: >-
https://yt3.googleusercontent.com/kFfAtp8wQM5wTqRzFn1wiZWdcJ5atGU1u-BnzpadbVFQJBThObAYNZTxsagdHnzW5m79G5A4pg=s900-c-k-c0x00ffffff-no-rj
totalSubscribers: 2170000
- displayName: 🩷La Barbie Jimenez 🩷
uniqueId: '@labarbiejimenez'
channelId: UC2Z5u_Azat1RoqK-7-Sy4Tg
avatarUrl: >-
https://yt3.googleusercontent.com/h6_4n7pOk4AAn93qpxZl0abQZjYtg4PtzxXnsPO3l4wF7p3d8271Q_F_TqeUDsvuQKA6aIPaxYo=s900-c-k-c0x00ffffff-no-rj
totalSubscribers: 1050000
- displayName: 🦋wishkhanna_🦋
uniqueId: '@wishkhanna____'
channelId: UC32P0rFNpMhz97Oast8Mdgg
avatarUrl: >-
https://yt3.googleusercontent.com/rubd3-FNnl6pEpm5po_t6J67FE0IV_p452ujgAlxs1QITLGzi-nObStp06dbR3Qz96RJ5gm1=s900-c-k-c0x00ffffff-no-rj
totalSubscribers: 1450000
- displayName: 🥜𝐀𝐧𝐲𝐚 𝐂𝐡𝐚𝐧🥜
uniqueId: '@yandere79'
channelId: UCVYsu-OqwXh9wF9eHERXcNg
avatarUrl: >-
https://yt3.googleusercontent.com/kOFqPM33m-b9YLSSjS499UciWpwZMJ0-MLmTjycnBUoGr3OCF2-yH8lMrT4VDgi4XznVX7TA9w=s900-c-k-c0x00ffffff-no-rj
totalSubscribers: 2250000
- displayName: 🤍cloudy express 🤍
uniqueId: '@cloudyexpress-cb3pf'
channelId: UCo7-sHv2yP_tk2FFbfwmILQ
avatarUrl: >-
https://yt3.googleusercontent.com/c5pVxWtJhkU12B3D_MS_pfEV-9wpwyxsCHHrOLP67tEQgAf5uNwreDaPHxIqIqS81LIRbjX8w8A=s900-c-k-c0x00ffffff-no-rj
totalSubscribers: 1030000
- displayName: 🙏Jay shri shyam🙏
uniqueId: '@bhaktisagar609'
channelId: UC2e-a4J25uO7Vqdz5s9D39w
avatarUrl: >-
https://yt3.googleusercontent.com/1onewDKzTDXArcN-SSOogr_-eGczRvnWi2jlcxMGaxSJq9e8DDMgFwfs7BpaXogQwfFt2Cm3=s900-c-k-c0x00ffffff-no-rj
totalSubscribers: 1810000
- displayName: 🙏 Pray Together 🙏
uniqueId: '@frastefano'
channelId: UCEISS2bKsVnyvPSGvK-q_mg
avatarUrl: >-
https://yt3.googleusercontent.com/lqbSpiP1yWva-3v1pbFlZ--tVLaQJuCwGP1vvoAi75-w-VqJe0QDzUxqtfwUfE25Qem15nxy3w=s900-c-k-c0x00ffffff-no-rj
totalSubscribers: 1270000
- displayName: 🖤BRK
uniqueId: '@mr.say3ed'
channelId: UCCQ7XwHCZetFk0zJWadP1Ww
avatarUrl: >-
https://yt3.googleusercontent.com/kr5zTRyltQF-7K7iCIiB9iMV1wOmvpRPYvUeIqa_KdxmzRwAe_FdEiS7heUG7bTJLibMP7HHUg=s900-c-k-c0x00ffffff-no-rj
totalSubscribers: 1160000
- displayName: 🖤 everytime BTS 🖤
uniqueId: '@everytimebts2517'
channelId: UCEi2lZb1oSZ7tDP5vi4U9tg
avatarUrl: >-
https://yt3.googleusercontent.com/YGNUzzRXD7hvz6Swqgs-NR7sZGiuKodJr15sLdf4tYPMyVXvw3M2ZTN9RJ3psNn5sHmJ3dhxxw=s900-c-k-c0x00ffffff-no-rj
totalSubscribers: 1110000
hasNextPage: true
nextOffset: 10
creditsUsed: 1
creditsAvailable: -1
traceId: f3430ba969f51fc42d633cb4fd00f86d
timestamp: 1767923571340
errorCode: ''
errorDescription: ''
success: true
'400':
description: Validation error.
content:
application/json:
schema:
type: object
title: ValidationErrorResponse
properties:
success:
const: false
error:
type: string
message:
type: string
timestamp:
type: integer
required:
- success
- error
- message
- timestamp
examples:
missing filters:
summary: Missing filters field
value:
success: false
error: VALIDATION_ERROR
message: At least 1 filter object is required.
timestamp: 1770099403116
invalid filterName:
summary: Invalid filterName
value:
success: false
error: VALIDATION_ERROR
message: >-
Invalid 'filterName'. For accepted values, see:
https://docs.creatordb.app/api-v3/configuring_advanced_search_filters#configuring-filters-for-youtube-advanced-search.
timestamp: 1770099403116
invalid pageSize:
summary: pageSize exceeds upper limit
value:
success: false
error: VALIDATION_ERROR
message: Exceeded max pageSize of 100. Must be between 1 and 100.
timestamp: 1770099403116
'429':
description: Exceeded quota or rate limit.
content:
application/json:
schema:
type: object
title: QuotaErrorResponse
properties:
success:
const: false
error:
type: string
message:
type: string
remainingPlanCredit:
type: number
required:
- success
- error
- message
- remainingPlanCredit
examples:
rate limit:
summary: Rate limit exceeded
value:
success: false
error: RATE_LIMIT_EXCEEDED
message: Too many requests. Please try again later.
quota exceeded:
summary: Credit quota exceeded
value:
success: false
error: QUOTA_EXCEEDED
message: Not enough credits to complete this request.
security:
- ApiKeyAuth: []
servers:
- url: https://apiv3.creatordb.app
description: Production Environment (CreatorDB Headless API V3)
x-codeSamples:
- lang: bash
label: cURL
source: |
curl -X POST "https://apiv3.creatordb.app/youtube/search" \
-H "Content-Type: application/json" \
-H "api-key: " \
-d '{
"filters":[
{
"filterName":
"totalSubscribers",
"op":">",
"value":1000000
}
],
"pageSize":10,
"offset":0
}'
components:
securitySchemes:
ApiKeyAuth:
type: apiKey
description: The valid CreatorDB API key for authentication.
name: api-key
in: header
````