> ## 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 Across Platforms

> Search for creators across YouTube, Instagram, and TikTok in a single request, instead of running a separate search on each platform. Each result is one creator, with their accounts on each platform grouped together.

You can search in three ways:

- **By attributes.** Filter on aggregate and main-platform attributes.
- **By a known account.** If you already know one of a creator's accounts, find their accounts on other platforms using a handle filter (`youtubeId`, `instagramId`, `tiktokId`) or a permanent ID filter (`youtubeChannelId`, `instagramNumericId`, `tiktokNumericId`). Permanent IDs don't change when a creator renames their handle.
- **By email address.** Find the creators associated with a list of email addresses using the `email` filter.

Each request requires at least 1 filter and accepts up to 10 filters.

By default, the `creators` list is sorted by `creatorDBScore` in descending order. To change the order, use the `sortBy` parameter.

Credit costs:

- **Standard requests** cost 1 credit per page.
- **Requests that include the `keywords` filter** cost 3 credits per page.
- **Requests that include the `email` filter** are charged per matched email address instead of per page. Each input address that matches at least one creator on the returned page costs 15 credits, even if it matches several creators. Addresses with no match cost nothing.

For all prices, see [API Credit Usage](/api-v3/api-credit-usage#creator).




## OpenAPI

````yaml /api-v3/api-v3.yaml post /creator/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: Creator
    description: >-
      Cross-platform creator endpoints. Each result is one creator, with their
      linked YouTube, Instagram, and TikTok accounts grouped together.
  - 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: Sponsor
    description: Sponsor analysis endpoints including sponsor search and sponsor reports.
  - name: TikTok
    description: >-
      TikTok creator data endpoints with metrics and advanced search
      functionality.
  - name: YouTube
    description: >-
      YouTube creator data endpoints including basic metrics, historical data,
      and detailed analytics.
paths:
  /creator/search:
    post:
      tags:
        - Creator
      summary: Search Creators Across Platforms
      description: >
        Search for creators across YouTube, Instagram, and TikTok in a single
        request, instead of running a separate search on each platform. Each
        result is one creator, with their accounts on each platform grouped
        together.


        You can search in three ways:


        - **By attributes.** Filter on aggregate and main-platform attributes.

        - **By a known account.** If you already know one of a creator's
        accounts, find their accounts on other platforms using a handle filter
        (`youtubeId`, `instagramId`, `tiktokId`) or a permanent ID filter
        (`youtubeChannelId`, `instagramNumericId`, `tiktokNumericId`). Permanent
        IDs don't change when a creator renames their handle.

        - **By email address.** Find the creators associated with a list of
        email addresses using the `email` filter.


        Each request requires at least 1 filter and accepts up to 10 filters.


        By default, the `creators` list is sorted by `creatorDBScore` in
        descending order. To change the order, use the `sortBy` parameter.


        Credit costs:


        - **Standard requests** cost 1 credit per page.

        - **Requests that include the `keywords` filter** cost 3 credits per
        page.

        - **Requests that include the `email` filter** are charged per matched
        email address instead of per page. Each input address that matches at
        least one creator on the returned page costs 15 credits, even if it
        matches several creators. Addresses with no match cost nothing.


        For all prices, see [API Credit
        Usage](/api-v3/api-credit-usage#creator).
      operationId: searchCreator
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                filters:
                  type: array
                  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`, `>`, `=`, `<`. <br /> - String fields accept:
                          `=`, `in`. <br /> - Number fields accept: `>`, `=`,
                          `<`. <br /> - Boolean fields accept: `=`
                      value:
                        anyOf:
                          - type: string
                          - type: number
                          - type: array
                            items:
                              type: string
                            minItems: 1
                            maxItems: 100
                          - type: boolean
                        description: >-
                          Type depends on the `filterName`. <br /> - String
                          fields accept `string` or `string[]`. <br /> - Number
                          fields accept `number`. <br /> - Boolean fields accept
                          `boolean`. <br /> - Operator `in` accepts `string[]`,
                          operator `=` accepts string for `string` fields.
                      isFuzzySearch:
                        type: boolean
                        default: false
                        description: >-
                          When `true`, performs a fuzzy match. Supported only
                          for the `keywords` and `searchName` filters. Setting
                          it on any other filter returns a 400 error.
                          `searchName` returns no results unless `isFuzzySearch`
                          is `true`.
                    required:
                      - filterName
                      - op
                      - value
                  minItems: 1
                  maxItems: 10
                  description: >-
                    Filter objects that include `filterName`, `op`, and `value`.
                    For the `keywords` and `searchName` filters, you can also
                    set the optional `isFuzzySearch`. For all accepted
                    `filterName` values and their data types, see [Configuring
                    Custom Search Filters and
                    Examples](/api-v3/configuring_advanced_search_filters#configuring-custom-cross-platform-creator-filter-search-criteria).
                desc:
                  type: boolean
                  default: true
                  description: >-
                    Sort order for results. `true` for descending, `false` for
                    ascending order. Defaults to `true`.
                sortBy:
                  type: string
                  enum:
                    - creatorDBScore
                    - mainPlatformFollowers
                    - followerGrowth
                    - addedDate
                    - lastActive
                  default: creatorDBScore
                  description: >-
                    Field to sort creators by. For example,
                    `mainPlatformFollowers` sorts by follower count on each
                    creator's primary platform. Defaults to `creatorDBScore`.
                pageSize:
                  type: integer
                  minimum: 1
                  maximum: 100
                  description: 'Number of results per page. Maximum: 100.'
                offset:
                  type: integer
                  minimum: 0
                  description: Number of records to skip before returning results.
              required:
                - filters
                - pageSize
                - offset
              description: >-
                Search for creators across YouTube, Instagram, and TikTok by
                attributes, by a known account, or by email address.
              example:
                filters:
                  - filterName: mainPlatform
                    op: in
                    value:
                      - youtube
                      - instagram
                  - filterName: country
                    op: in
                    value:
                      - USA
                      - GBR
                  - filterName: mainPlatformFollowers
                    op: '>'
                    value: 100000
                  - filterName: hasEmail
                    op: '='
                    value: true
                pageSize: 50
                offset: 0
                sortBy: creatorDBScore
                desc: true
      responses:
        '200':
          description: Creator search results returned successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      creators:
                        type: array
                        items:
                          type: object
                          properties:
                            creatorId:
                              type: string
                              description: >-
                                A unique ID that CreatorDB assigns to each
                                creator to link their YouTube, Instagram, and
                                TikTok accounts. It's the only identifier
                                guaranteed to match exactly one creator. The ID
                                is stable but not guaranteed to be permanent. If
                                a stored `creatorId` no longer returns a result,
                                the creator hasn't necessarily been deleted.
                                Search for the creator again using one of their
                                platform accounts to get their current
                                `creatorId`.
                              example: yt_UCX6OQ3DkcsbYNE6H8uQQuVA
                            displayName:
                              type: string
                              description: The creator's display name.
                              example: MrBeast
                            avatarUrl:
                              type: string
                              description: The creator's profile picture URL.
                              example: >-
                                https://yt3.googleusercontent.com/ytc/AIdro_mrbeast
                            country:
                              type: string
                              description: >-
                                The country in **ISO 3166-1 alpha-3** format.
                                For details, see [Country
                                Codes](/api-v3/country-code).
                              example: USA
                            mainLanguage:
                              type: string
                              description: >-
                                The language in **ISO 639-3** format. For
                                details, see [Language
                                Codes](/api-v3/language-code).
                              example: eng
                            creatorDBScore:
                              type: integer
                              description: >-
                                A score from 0 to 100 that CreatorDB calculates
                                to measure a creator's performance on social
                                media. Higher scores indicate stronger
                                performance. This is the same score shown in the
                                CreatorDB app. For how the score is calculated,
                                see [Data
                                Analysis](/creatordb_app/faqs/data_analysis#what-does-the-creatordb-score-mean).
                              example: 98
                            mainPlatform:
                              type: string
                              enum:
                                - youtube
                                - instagram
                                - tiktok
                              description: The creator's primary platform.
                              example: youtube
                            mainPlatformFollowers:
                              description: >-
                                The number of followers or subscribers on the
                                creator's primary platform.
                              type: integer
                              example: 513000000
                            platforms:
                              type: object
                              properties:
                                youtube:
                                  type: array
                                  items:
                                    type: object
                                    properties:
                                      uniqueId:
                                        type: string
                                        description: >-
                                          The creator's YouTube handle, including
                                          the leading `@`. If CreatorDB doesn't
                                          have the handle on file, this field is
                                          omitted from the response.
                                        example: '@mrbeast'
                                      url:
                                        type: string
                                        description: >-
                                          The URL of the creator's YouTube
                                          account.
                                        example: >-
                                          https://www.youtube.com/channel/UCX6OQ3DkcsbYNE6H8uQQuVA
                                      channelId:
                                        type: string
                                        description: >-
                                          The creator's YouTube channel ID, which
                                          starts with `UC` and stays the same if
                                          the creator changes their handle. You
                                          can pass it to `/youtube/profile` or use
                                          it with the `youtubeChannelId` filter.
                                          If CreatorDB doesn't have the channel ID
                                          on file, this field is omitted from the
                                          response. Use the handle (`uniqueId`)
                                          instead.
                                        example: UCX6OQ3DkcsbYNE6H8uQQuVA
                                    description: One of the creator's YouTube accounts.
                                  description: >-
                                    The creator's YouTube accounts. The first
                                    entry is the creator's main YouTube account,
                                    and any other entries are secondary
                                    accounts. If the creator has no YouTube
                                    account, this is an empty array, never
                                    `null`. Currently there's at most one
                                    account per platform. Accounts may be added
                                    later, with no limit on the number of
                                    entries.
                                instagram:
                                  type: array
                                  items:
                                    type: object
                                    properties:
                                      uniqueId:
                                        type: string
                                        description: >-
                                          The creator's Instagram handle. If
                                          CreatorDB doesn't have the handle on
                                          file, this field is omitted from the
                                          response.
                                        example: mrbeast
                                      url:
                                        type: string
                                        description: >-
                                          The URL of the creator's Instagram
                                          account.
                                        example: https://www.instagram.com/mrbeast
                                      id:
                                        type: string
                                        description: >-
                                          The creator's numeric Instagram ID,
                                          which stays the same if the creator
                                          changes their handle. You can use it
                                          with the `instagramNumericId` filter. If
                                          CreatorDB doesn't have the ID on file,
                                          this field is omitted from the response.
                                          Use the handle (`uniqueId`) instead.
                                        example: '2278169415'
                                    description: One of the creator's Instagram accounts.
                                  description: >-
                                    The creator's Instagram accounts. The first
                                    entry is the creator's main Instagram
                                    account, and any other entries are secondary
                                    accounts. If the creator has no Instagram
                                    account, this is an empty array, never
                                    `null`. Currently there's at most one
                                    account per platform. Accounts may be added
                                    later, with no limit on the number of
                                    entries.
                                tiktok:
                                  type: array
                                  items:
                                    type: object
                                    properties:
                                      uniqueId:
                                        type: string
                                        description: >-
                                          The creator's TikTok handle. If
                                          CreatorDB doesn't have the handle on
                                          file, this field is omitted from the
                                          response.
                                        example: mrbeast
                                      url:
                                        type: string
                                        description: The URL of the creator's TikTok account.
                                        example: https://www.tiktok.com/@mrbeast
                                      id:
                                        type: string
                                        description: >-
                                          The creator's numeric TikTok ID, which
                                          stays the same if the creator changes
                                          their handle. You can use it with the
                                          `tiktokNumericId` filter. If CreatorDB
                                          doesn't have the ID on file, this field
                                          is omitted from the response. Use the
                                          handle (`uniqueId`) instead.
                                        example: '6614519312189947909'
                                    description: One of the creator's TikTok accounts.
                                  description: >-
                                    The creator's TikTok accounts. The first
                                    entry is the creator's main TikTok account,
                                    and any other entries are secondary
                                    accounts. If the creator has no TikTok
                                    account, this is an empty array, never
                                    `null`. Currently there's at most one
                                    account per platform. Accounts may be added
                                    later, with no limit on the number of
                                    entries.
                              required:
                                - youtube
                                - instagram
                                - tiktok
                              description: >-
                                The creator's accounts on YouTube, Instagram,
                                and TikTok. In each array, the first entry is
                                the creator's main account on that platform. If
                                the creator has no account on a platform, that
                                platform's array is empty, never `null`.
                            totalAccounts:
                              type: integer
                              description: >-
                                The total number of accounts the creator has
                                across YouTube, Instagram, and TikTok, including
                                main and secondary accounts. To count a
                                creator's accounts on one platform, use the
                                number of entries in that platform's array, such
                                as `platforms.youtube`.
                              example: 3
                            aggregateFollowers:
                              type: integer
                              description: >-
                                The creator's total number of followers
                                (including YouTube subscribers) across YouTube,
                                Instagram, and TikTok.
                              example: 739769509
                            hasEmail:
                              type: boolean
                              description: >-
                                `true` when CreatorDB has a contact email for
                                any of the creator's YouTube, Instagram, or
                                TikTok accounts. The `email` filter on
                                `/creator/search` searches the same emails, so
                                creators with `hasEmail: false` can't be found
                                by email.
                            hasAgencyRep:
                              type: boolean
                              description: >-
                                `true` when an agency contact was detected in
                                the emails of any of the creator's YouTube,
                                Instagram, or TikTok accounts. `false` means
                                none was detected, including for creators with
                                no email on file. It doesn't mean the creator
                                has no agency.
                            lastPublishTime:
                              type: integer
                              description: >-
                                Time of the latest published content across the
                                creator's linked YouTube, Instagram, and TikTok
                                accounts, represented as a Unix timestamp in
                                milliseconds.
                              example: 1786464006000
                            addedDate:
                              type: integer
                              description: >-
                                Time CreatorDB added the creator to its
                                database, represented as a Unix timestamp in
                                milliseconds.
                              example: 1741783824215
                            matchedIds:
                              type: array
                              items:
                                type: string
                              description: >-
                                The handles or IDs from your request that
                                matched this creator, in the order you sent
                                them. Use this field to see which of your inputs
                                each result corresponds to. If one input matches
                                more than one creator, it appears in this field
                                for each of them. Included only when your
                                request uses one of these filters: `youtubeId`,
                                `instagramId`, `tiktokId`, `youtubeChannelId`,
                                `instagramNumericId`, `tiktokNumericId`, or
                                `creatorId`. Otherwise, this field is omitted
                                from the response.
                              example:
                                - therock
                            matchedEmails:
                              type: array
                              items:
                                type: string
                              description: >-
                                The email addresses from your request that
                                matched this creator, in the order you sent
                                them. Use this field to see which of your inputs
                                each result corresponds to. If one address
                                matches more than one creator, it appears in
                                this field for each of them. Included only when
                                your request uses the `email` filter. Otherwise,
                                this field is omitted from the response.
                              example:
                                - jane@janescreates.com
                          required:
                            - creatorId
                            - displayName
                            - avatarUrl
                            - country
                            - mainLanguage
                            - creatorDBScore
                            - mainPlatform
                            - mainPlatformFollowers
                            - platforms
                            - totalAccounts
                            - aggregateFollowers
                            - hasEmail
                            - hasAgencyRep
                            - lastPublishTime
                            - addedDate
                          description: >-
                            One creator, with their linked accounts on YouTube,
                            Instagram, and TikTok.
                        description: Creators that match your search filters.
                      totalResults:
                        type: integer
                        minimum: 0
                        description: Total number of creators matching the filters.
                        example: 20262998
                      offset:
                        type: integer
                        minimum: 0
                        description: >-
                          The number of results skipped before this page. This
                          is the same value as the `offset` in your request.
                          There's another page while `offset` plus `pageSize` is
                          less than `totalResults`. A page can have fewer than
                          `pageSize` results before the last page.
                        example: 0
                      pageSize:
                        type: integer
                        minimum: 1
                        maximum: 100
                        description: >-
                          The maximum number of results on this page. This is
                          the same value as the `pageSize` in your request.
                        example: 50
                    required:
                      - creators
                      - totalResults
                      - offset
                      - pageSize
                    description: >-
                      Creator search response with matching creators and
                      pagination information.
                  traceId:
                    type: string
                    description: Unique trace ID for each request.
                    example: f8e4a3b2c1d0e9f8a7b6c5d4e3f2a1b0
                  timestamp:
                    type: integer
                    description: >-
                      Time the response was generated, represented as a Unix
                      timestamp in milliseconds.
                    example: 1750732453635
                  creditsAvailable:
                    type: number
                    description: >-
                      Number of API credits remaining. Equals
                      `planCreditsAvailable` plus `purchasedCreditsAvailable`.
                    example: 975
                  creditsUsed:
                    type: number
                    description: Number of API credits consumed by this request.
                    example: 25
                  planCreditsAvailable:
                    type: number
                    description: Plan credits remaining after this request.
                    examples:
                      - 900
                  purchasedCreditsAvailable:
                    type: number
                    description: Purchased credits remaining after this request.
                    examples:
                      - 75
                  keyCreditsAvailable:
                    type: number
                    description: >-
                      Remaining credits this API key can spend after this
                      request, before reaching its spend limit. Present only
                      when the key has a spend limit.
                    examples:
                      - 4975
                  errorCode:
                    type: string
                    description: >-
                      Error code returned if the request fails. Empty if the
                      request is successful.
                    example: ''
                  errorDescription:
                    type: string
                    description: >-
                      Description of the error. Empty if the request is
                      successful.
                    example: ''
                  success:
                    type: boolean
                    description: '`true` if the request is successful.'
                    example: true
                required:
                  - data
                  - traceId
                  - timestamp
                  - creditsAvailable
                  - creditsUsed
                  - planCreditsAvailable
                  - purchasedCreditsAvailable
                  - errorCode
                  - errorDescription
                  - success
                description: Creator Search API response with creator list and pagination.
        '402':
          description: >-
            Insufficient credits, or the API key has reached its spend limit.
            Nothing is charged.
          content:
            application/json:
              schema:
                type: object
                title: PaymentRequiredErrorResponse
                properties:
                  success:
                    const: false
                  error:
                    type: string
                    description: >-
                      The type of error. Use `errorCode` to handle errors in
                      your code.
                  message:
                    type: string
                  errorCode:
                    type: string
                    enum:
                      - INSUFFICIENT_CREDITS
                      - KEY_SPEND_THRESHOLD_EXCEEDED
                  traceId:
                    type: string
                  timestamp:
                    type: integer
                  details:
                    type: object
                    properties:
                      creditsAvailable:
                        type: number
                        description: >-
                          For `INSUFFICIENT_CREDITS`, your remaining credit
                          balance. For `KEY_SPEND_THRESHOLD_EXCEEDED`, the
                          credits remaining under this key's spend limit.
                      creditsUsed:
                        type: number
                        description: Always `0`.
                required:
                  - success
                  - error
                  - message
                  - errorCode
                  - traceId
                  - timestamp
                  - details
              examples:
                insufficient credits:
                  summary: Credit balance exhausted
                  value:
                    success: false
                    error: PaymentRequiredError
                    message: Insufficient credits
                    errorCode: INSUFFICIENT_CREDITS
                    traceId: c4e5af55f3bb9d11cc20481bfc80c1df
                    timestamp: 1791959292593
                    details:
                      creditsAvailable: 0
                      creditsUsed: 0
                key spend limit:
                  summary: API key spend limit reached
                  value:
                    success: false
                    error: PaymentRequiredError
                    message: API key spending limit exceeded
                    errorCode: KEY_SPEND_THRESHOLD_EXCEEDED
                    traceId: c4e5af55f3bb9d11cc20481bfc80c1df
                    timestamp: 1791959292593
                    details:
                      creditsAvailable: 0
                      creditsUsed: 0
      security:
        - ApiKeyAuth: []
      servers:
        - url: https://apiv3.creatordb.app
          description: Production Environment (CreatorDB Headless API V3)
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      description: The valid CreatorDB API key for authentication.
      name: api-key
      in: header

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.