> ## 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 for YouTube creators based on custom filter criteria

> 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. The `creatorList` is, by default, sorted by `displayName`. Custom sorting can be applied using the `sortBy` parameter.

<ParamField header="api-key" type="string" required>
  You need a valid api-key for authentication.
</ParamField>

<ParamField body="filters" type="object[]" required>
  An array of filter objects that includes: `filterName`, `op`, and `value`. For the full list of supported `filterName` and their corresponding data types, please refer to [Configuring Custom Search Filters and Examples](http://docs.creatordb.app/api-v3/configuring_advanced_search_filters#available-filtername-&-sortby). You can combine multiple filters in a single request to narrow down your search results. The API supports up to 10 filters per request.
  Maximum array length: `10`

  <Expandable title="properties">
    <ParamField body="filterName" type="string" required>
      The field to apply the filter on.

      <Expandable title="properties">
        <ParamField body="displayName" type="string">
          The name of the YouTube channel. <br />
          Supported operators include: `in`, `=`
        </ParamField>

        <ParamField body="uniqueId" type="string">
          The YouTube username/handle. <br /> **Constraint:** Must be 3-100 characters, allowing letters, numbers, dots, hyphens, and underscores. Can include optional `@` prefix (e.g., `mrbeast` or `@mrbeast`). <br />
          Supported operators include: `in`, `=`
        </ParamField>

        <ParamField body="mainCategory" type="string">
          The primary category of the channel’s content. <br />
          Supported operators include: `in`, `=`
        </ParamField>

        <ParamField body="country" type="string">
          The country associated with the channel. <br />
          **Constraint:** Must be in **ISO 3166-1 alpha-3** format (e.g., `TWN`, `USA`).<br />
          Supported operators include: `in`, `=`
        </ParamField>

        <ParamField body="mainLanguage" type="string">
          The main language of the channel’s videos. <br /> **Constraint:** Must be in **ISO 639-3** format.<br />
          Supported operators include: `in`, `=`
        </ParamField>

        <ParamField body="languages" type="string">
          All languages used in the channel’s videos. <br />
          **Constraint:** Must be in **ISO 639-3** format.<br />
          Supported operators include: `in`, `=`
        </ParamField>

        <ParamField body="secondLanguage" type="string">
          The secondary language used in the channel’s videos.\
          <br /> **Constraint:** Must be in **ISO 639-3** format. <br />
          Supported operators include: `in`, `=`
        </ParamField>

        <ParamField body="hashtags" type="string">
          Keywords/tags used in video descriptions or tags.
          Supported operators include: `in`, `=`
        </ParamField>

        <ParamField body="niches" type="string">
          Represents unified content theme identified by CreatorDB’s AI model.
          Supported operators include: `in`, `=`
        </ParamField>

        <ParamField body="topics" type="string">
          YouTube specific topics associated with the channel.
          Supported operators include: `in`, `=`
        </ParamField>

        <ParamField body="mainAudienceLocation" type="string">
          The country where the channel’s audience is most concentrated. <br />
          **Constraint:** Must be in **ISO 3166-1 alpha-3** format. <br />
          Supported operators include: `in`, `=`
        </ParamField>

        <ParamField body="mainAudienceAge" type="string">
          The primary age range of the channel’s audience. <br />
          **Allowed Values:** `13-17`, `18-24`, `25-34`, `35-44`, `45-54`, `55-64`, `65+`. <br />
          Supported operators include: `in`, `=`
        </ParamField>

        <ParamField body="mainAudienceGender" type="string">
          The dominant gender group among the channel’s audience. <br />
          **Allowed Values:** `male`, `female`. <br />
          Supported operators include: `in`, `=`
        </ParamField>

        <ParamField body="totalSubscribers" type="number">
          The total number of subscribers of the YouTube channel. <br />
          Supported operators include: `>`, `=`, `<`
        </ParamField>

        <ParamField body="totalContents" type="number">
          The total number of videos uploaded by the creator. <br />
          Supported operators include: `>`, `=`, `<`
        </ParamField>

        <ParamField body="totalViews" type="number">
          The total number of views across all videos. <br />
          Supported operators include: `>`, `=`, `<`
        </ParamField>

        <ParamField body="lastPublishTime" type="number">
          The timestamp of the most recent video upload (Unix timestamp in milliseconds). <br />
          Supported operators include: `>`, `=`, `<`
        </ParamField>

        <ParamField body="subscriberGrowthIn30d" type="number">
          The growth rate of subscribers in the past 30 days. <br />
          Supported operators include: `>`, `=`, `<`
        </ParamField>

        <ParamField body="avgRecentVideosLikes" type="number">
          Average likes per video (based on recent long-form videos). <br />
          Supported operators include: `>`, `=`, `<`
        </ParamField>

        <ParamField body="avgVideosLikesAll" type="number">
          Average likes per video (based on all-time long-form videos). <br />
          Supported operators include: `>`, `=`, `<`
        </ParamField>

        <ParamField body="medianRecentVideosLikes" type="number">
          Median likes per video (based on recent long-form videos). <br />
          Supported operators include: `>`, `=`, `<`
        </ParamField>

        <ParamField body="medianVideosLikesAll" type="number">
          Median likes per video (based on all-time long-form videos). <br />
          Supported operators include: `>`, `=`, `<`
        </ParamField>

        <ParamField body="avgRecentVideosComments" type="number">
          Average comments per video (based on recent long-form videos). <br />
          Supported operators include: `>`, `=`, `<`
        </ParamField>

        <ParamField body="avgVideosCommentsAll" type="number">
          Average comments per video (based on all-time long-form videos).<br />
          Supported operators include: `>`, `=`, `<`
        </ParamField>

        <ParamField body="avgRecentVideosViews" type="number">
          Average views per video (based on recent long-form videos). <br />
          Supported operators include: `>`, `=`, `<`
        </ParamField>

        <ParamField body="avgVideosViewsAll" type="number">
          Average views per video (based on all-time long-form videos). <br />
          Supported operators include: `>`, `=`, `<`
        </ParamField>

        <ParamField body="medianRecentVideosViews" type="number">
          Median views per video (based on recent long-form videos). <br />
          Supported operators include: `>`, `=`, `<`
        </ParamField>

        <ParamField body="medianVideosViewsAll" type="number">
          Median views per video (based on all-time long-form videos). <br />
          Supported operators include: `>`, `=`, `<`
        </ParamField>

        <ParamField body="avgRecentVideosEngagementRate" type="number">
          Average engagement rate for recent long-form videos. Calculated as $ \frac {(Likes + Comments)}{Subscribers}$. <br />
          Supported operators include: `>`, `=`, `<`
        </ParamField>

        <ParamField body="avgVideosEngagementRateAll" type="number">
          Average engagement rate for all-time long-form videos. <br />
          Supported operators include: `>`, `=`, `<`
        </ParamField>

        <ParamField body="avgRecentShortsViews" type="number">
          Average views per short (based on recent shorts). <br />
          Supported operators include: `>`, `=`, `<`
        </ParamField>

        <ParamField body="avgShortsViewsAll" type="number">
          Average views per short (based on all-time shorts) <br />
          Supported operators include: `>`, `=`, `<`
        </ParamField>

        <ParamField body="medianRecentShortsViews" type="number">
          Median views per short (based on recent shorts). <br />
          Supported operators include: `>`, `=`, `<`
        </ParamField>

        <ParamField body="medianShortsViewsAll" type="number">
          Median views per short (based on all-time shorts). <br />
          Supported operators include: `>`, `=`, `<`
        </ParamField>

        <ParamField body="avgShortsLikesAll" type="number">
          Average likes per short (based on recent shorts). <br />
          Supported operators include: `>`, `=`, `<`
        </ParamField>

        <ParamField body="medianRecentShortsLikes" type="number">
          Median likes per short (based on recent shorts). <br />
          Supported operators include: `>`, `=`, `<`
        </ParamField>

        <ParamField body="medianShortsLikesAll" type="number">
          Median likes per short (based on all-time shorts). <br />
          Supported operators include: `>`, `=`, `<`
        </ParamField>

        <ParamField body="avgRecentShortsComments" type="number">
          Average comments per short (based on recent shorts). <br />
          Supported operators include: `>`, `=`, `<`
        </ParamField>

        <ParamField body="avgShortsCommentsAll" type="number">
          Average comments per short (based on all-time shorts). <br />
          Supported operators include: `>`, `=`, `<`
        </ParamField>

        <ParamField body="avgRecentShortsEngagementRate" type="number">
          Average engagement rate for recent shorts. Calculated as $ \frac {(Likes + Comments)}{Subscribers}$. <br />
          Supported operators include: `>`, `=`, `<`
        </ParamField>

        <ParamField body="avgShortsEngagementRateAll" type="number">
          Average engagement rate for all-time shorts. <br />
          Supported operators include: `>`, `=`, `<`
        </ParamField>

        <ParamField body="avgRecentContentsViews" type="number">
          Average views across all content types $(Videos + Shorts)$ in recent posts.<br />
          Supported operators include: `>`, `=`, `<`
        </ParamField>

        <ParamField body="avgRecentContentsLikes" type="number">
          Average likes across all content types $(Videos + Shorts)$ in recent posts. <br />
          Supported operators include: `>`, `=`, `<`
        </ParamField>

        <ParamField body="avgRecentContentsComments" type="number">
          Average comments across all content types $(Videos + Shorts)$ in recent posts. <br />
          Supported operators include: `>`, `=`, `<`
        </ParamField>

        <ParamField body="avgRecentContentsEngagementRate" type="number">
          Average engagement rate across all content types in recent posts. <br />
          Supported operators include: `>`, `=`, `<`
        </ParamField>

        <ParamField body="avgRecentContentsViewsGrowth" type="number">
          Growth rate of average views across all content types in recent posts. <br />
          Supported operators include: `>`, `=`, `<`
        </ParamField>

        <ParamField body="avgRecentContentsLikesGrowth" type="number">
          Growth rate of average likes across all content types in recent posts. <br />
          Supported operators include: `>`, `=`, `<`
        </ParamField>

        <ParamField body="avgRecentContentsCommentsGrowth" type="number">
          Growth rate of average comments across all content types in recent posts. <br />
          Supported operators include: `>`, `=`, `<`
        </ParamField>

        <ParamField body="avgRecentContentsEngagementRateGrowth" type="number">
          Growth rate of average engagement rate across all content types in recent posts. <br />
          Supported operators include: `>`, `=`, `<`
        </ParamField>

        <ParamField body="avgRecentVideosViewsGrowth" type="number">
          Growth rate of average views per long-form video in recent posts. <br />
          Supported operators include: `>`, `=`, `<`
        </ParamField>

        <ParamField body="avgRecentVideosLikesGrowth" type="number">
          Growth rate of average likes per long-form video in recent posts. <br />
          Supported operators include: `>`, `=`, `<`
        </ParamField>

        <ParamField body="avgRecentShortsCommentsGrowth" type="number">
          Growth rate of average comments per short in recent posts. <br />
          Supported operators include: `>`, `=`, `<`
        </ParamField>

        <ParamField body="avgRecentShortsEngagementRateGrowth" type="number">
          Growth rate of average engagement rate per short in recent posts. <br />
          Supported operators include: `>`, `=`, `<`
        </ParamField>

        <ParamField body="subscriberCountPercentile" type="number">
          Percentile ranking of subscriber count compared to all YouTube channels (0-100). <br />
          Supported operators include: `>`, `=`, `<`
        </ParamField>

        <ParamField body="avgContentViewsPercentile" type="number">
          Percentile ranking of average content views compared to all YouTube channels (0-100). <br />
          Supported operators include: `>`, `=`, `<`
        </ParamField>

        <ParamField body="avgContentEngagementPercentile" type="number">
          Percentile ranking of average content engagement compared to all YouTube channels (0-100). <br />
          Supported operators include: `>`, `=`, `<`
        </ParamField>

        <ParamField body="subscriberCountPercentileGrowth" type="number">
          Growth rate of subscriber count percentile ranking. <br />
          Supported operators include: `>`, `=`, `<`
        </ParamField>

        <ParamField body="avgContentViewsPercentileGrowth" type="number">
          Growth rate of average content views percentile ranking. <br />
          Supported operators include: `>`, `=`, `<`
        </ParamField>

        <ParamField body="avgContentEngagementPercentileGrowth" type="number">
          Growth rate of average content engagement percentile ranking. <br />
          Supported operators include: `>`, `=`, `<`
        </ParamField>

        <ParamField body="platformScore" type="number">
          CreatorDB proprietary platform score indicating overall influence. <br />
          Supported operators include: `>`, `=`, `<`
        </ParamField>

        <ParamField body="joinedDate" type="number">
          The timestamp when the channel was created (Unix timestamp in milliseconds). <br />
          Supported operators include: `>`, `=`, `<`
        </ParamField>

        <ParamField body="contentsIn30Days" type="number">
          Number of videos published in the last 30 days. <br />
          Supported operators include: `>`, `=`, `<`
        </ParamField>

        <ParamField body="contentsIn90Days" type="number">
          Number of videos published in the last 90 days. <br />
          Supported operators include: `>`, `=`, `<`
        </ParamField>

        <ParamField body="audienceMaleRatio" type="number">
          The percentage of male subscribers in the channel’s audience (0-100). <br />
          Supported operators include: `>`, `=`, `<`
        </ParamField>

        <ParamField body="audienceFemaleRatio" type="number">
          The percentage of female subscribers in the channel’s audience (0-100). <br />
          Supported operators include: `>`, `=`, `<`
        </ParamField>

        <ParamField body="hasSponsors" type="boolean">
          Indicates whether the channel has published sponsored content. <br />
          Supported operators include: `=`
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="op" type="enum<string>" required>
      The comparison operator. Available values include `in`, `>`, `=`, `<`. <br />

      * `String` fields support: `=`, `in`. <br />
      * `Number` fields support: `>`, `=`, `<`. <br />
      * `Boolean` fields support: `=`

      Available options: `in`, `>`, `=`, `<`
    </ParamField>

    <ParamField body="value" type="string" required>
      The data type depends on the `filterName`. <br />

      * String fields require `string` or `string[]`. <br />
      * Number fields require `number`. <br />
      * Boolean fields require `boolean`. <br />
      * Operator `in` requires `string[]`, operator `=` requires `string` for string fields.
    </ParamField>

    <ParamField body="isFuzzySearch" type="boolean" default="false">
      When set to `true`, the filter will perform a fuzzy match for string-type values. Only applicable when the `filterName` corresponds to a string field. <br />
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="pageSize" type="integer" required>
  Specifies the maximum number of results to return in a single response. The upper limit is 100. <br />
  Required range: `1 ≤ x ≤ 100`
</ParamField>

<ParamField body="offset" type="integer" required>
  Indicates the number of records to skip before starting to return results. Used for pagination. <br />
  Required range: `x ≥ 0`
</ParamField>

<ParamField body="desc" type="integer">
  Determines the sort order. When set to `true`, results will be in descending order. When `false`, results will be in ascending order.
</ParamField>

<ParamField body="sortBy" type="string">
  The field to sort results by. For example, if the value is `totalFollowers`, the creators that meet the search criteria are organized by the number of followers they have.
</ParamField>

<ResponseField name="id" type="string" required>
  Unique identifier for the newly created user
</ResponseField>

<ResponseField name="email" type="string" required>
  User's email address
</ResponseField>