> ## 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.

# Creator Search

> Search for creators across YouTube, Instagram, and TikTok and get one row per creator, or resolve accounts you already know to a single creator.

`POST https://apiv3.creatordb.app/creator/search`

Unlike `{platform}/search` endpoints that return **accounts**, `creator/search` returns **people**. Each row is one creator, with their linked YouTube, Instagram, and TikTok accounts attached, so a multi-platform creator appears once instead of once per platform.

Use `creator/search` for two scenarios:

* **Discovery**: Find creators by attributes such as country, language, follower count, keywords, or sponsorship history.
* **Resolution**: Match accounts you already have to their creator, including uncovering the creator's unknown accounts on other platforms.

> [!NOTE]
>
> To search creator accounts within a single platform, use [`youtube/search`](https://docs.creatordb.app/api-reference/youtube/search-creators), [`instagram/search`](https://docs.creatordb.app/api-reference/instagram/search-creators), or [`tiktok/search`](https://docs.creatordb.app/api-reference/tiktok/search-creators). Those return richer per-platform metrics. `creator/search` trades that depth for the cross-platform view.

## Request

This example resolves a YouTube channel ID to its creator.

```json theme={null}
{
  "filters": [
    { "filterName": "youtubeChannelId", "op": "=", "value": "UCX6OQ3DkcsbYNE6H8uQQuVA" }
  ],
  "sortBy": "creatorDBScore",
  "desc": true,
  "pageSize": 50,
  "offset": 0
}
```

| Name | Type | Required | Description |
| - | - | - | - |
| `filters` | object\[] | Yes | Filter objects with `filterName`, `op`, and `value`. Minimum **1**. Maximum **10** filters per request. |
| `sortBy` | string | No | The field to sort results by. By default, results are sorted by `creatorDBScore`. Accepted values: `creatorDBScore`, `mainPlatformFollowers`, `followerGrowth`, `addedDate`, `lastActive`. |
| `desc` | boolean | No | Sort direction. Set to `true` for descending order or `false` for ascending order. Defaults to `true`. |
| `pageSize` | number | Yes | Number of results per page, from **1** to **100**. |
| `offset` | number | Yes | Number of results to skip. Minimum **0**. |

## Filters

The filters that you can use in `creator/search` fall into three categories: Discovery, Resolution, and Fuzzy matching. Each category has its own set of filters and usage guidelines. For the filters in each category, see [Configuring Custom Search Filters and Examples](https://docs.creatordb.app/api-v3/configuring_advanced_search_filters.md#configuring-custom-cross-platform-creator-filter-search-criteria).

## Response

```json theme={null}
{
  "data": {
    "creators": [
      {
        "creatorId": "yt_UCX6OQ3DkcsbYNE6H8uQQuVA",
        "displayName": "MrBeast",
        "avatarUrl": "https://example.com/avatar.jpg",
        "country": "USA",
        "mainLanguage": "eng",
        "creatorDBScore": 97,
        "mainPlatform": "youtube",
        "mainPlatformFollowers": 525000000,
        "aggregateFollowers": 761834625,
        "totalAccounts": 3,
        "platforms": {
          "youtube": [
            { "channelId": "UCX6OQ3DkcsbYNE6H8uQQuVA", "uniqueId": "@mrbeast", "url": "https://www.youtube.com/channel/UCX6OQ3DkcsbYNE6H8uQQuVA" }
          ],
          "instagram": [
            { "id": "2278169415", "uniqueId": "mrbeast", "url": "https://www.instagram.com/mrbeast" }
          ],
          "tiktok": [
            { "id": "6614519312189947909", "uniqueId": "mrbeast", "url": "https://www.tiktok.com/@mrbeast" }
          ]
        },
        "hasEmail": false,
        "hasAgencyRep": false,
        "lastPublishTime": 1793633137000,
        "addedDate": 1741783824215,
        "matchedIds": ["UCX6OQ3DkcsbYNE6H8uQQuVA"]
      }
    ],
    "totalResults": 1,
    "offset": 0,
    "pageSize": 50
  },
  "creditsUsed": 1,
  "creditsAvailable": 98452,
  "planCreditsAvailable": 0,
  "purchasedCreditsAvailable": 98452,
  "traceId": "d052411b141435a0a47bf503598ffa0e",
  "timestamp": 1789689600000,
  "errorCode": "",
  "errorDescription": "",
  "success": true
}
```

| Field | Description |
| - | - |
| `creatorId` | Stable but not permanent: CreatorDB can reissue it when it rebuilds a creator record, and IDs will change in a planned data migration. Treat it as an opaque string. If a stored `creatorId` stops returning a result, search again by one of the following platform IDs: `youtubeChannelId`, `instagramNumericId`, or `tiktokNumericId`. Use the platform ID instead because handles can change.  Read `creatorId` from the result. One account can be linked to more than one creator, so the search can return several results. Use `matchedIds` and `platforms` to find a specific creator. |
| `displayName` · `avatarUrl` | The display name and profile image URL, taken from the creator's main platform. |
| `country` · `mainLanguage` | Represented in ISO 3166-1 alpha-3 and ISO 639-3 format, respectively. For details, see [Country Codes](https://docs.creatordb.app/api-v3/country-code.md) and [Language Codes](https://docs.creatordb.app/api-v3/language-code.md). |
| `creatorDBScore` | A 0 to 100 score. For a creator with one account, it's that account's score. For a creator with several accounts, it's the average of the account scores, weighted by each account's follower ranking (its follower percentile on its platform), then rounded to a whole number. For example, a YouTube account with a score of 90 and a follower percentile of 0.9, plus an Instagram account with a score of 60 and a follower percentile of 0.3, give (90 × 0.9 + 60 × 0.3) ÷ (0.9 + 0.3) = 82.5, returned as 83, not the plain average of 75. Filter with `>` or `<`. |
| `mainPlatform` · `mainPlatformFollowers` | The creator's main platform and its follower or subscriber count. |
| `aggregateFollowers` | Total followers and subscribers across all linked accounts. Not deduplicated for audience overlap: a fan who follows the creator on both YouTube and Instagram is counted twice, so the total can be higher than the creator's unique audience. Is limited to the sum of up to three accounts for a creator, with one account per platform. |
| `totalAccounts` | Number of linked accounts across all platforms. Minimum: 1, Maximum: 3. |
| `platforms` | Linked accounts, grouped by `youtube`, `instagram`, and `tiktok` arrays. The first entry (`[0]`) is the creator's account with the most followers on that platform. Today, each platform has at most one account. A platform the creator isn't on returns an empty array, not `null`. Each account includes whichever of the URL, handle and platform ID CreatorDB has. Missing ones are left out. |
| `hasEmail` · `hasAgencyRep` | `hasEmail` is `true` when CreatorDB has an email address for the creator. `hasAgencyRep` is `true` when CreatorDB detected agency representation. `false` means no agency was detected, including for creators with no email on file. It doesn't mean the creator has no agency. |
| `lastPublishTime` | Time of the creator's most recent post across linked accounts, represented as a Unix timestamp in milliseconds. |
| `addedDate` | Time the creator record was added to CreatorDB, represented as a Unix timestamp in milliseconds. |
| `matchedIds` · `matchedEmails` | `matchedIds` is included only when you use one of the seven ID and handle filters (`creatorId`, `youtubeChannelId`, `youtubeId`, `instagramId`, `instagramNumericId`, `tiktokId`, `tiktokNumericId`). `matchedEmails` is included only when you use the `email` filter. Each lists the inputs that matched this creator, in the order you sent them. For these filters, see [Configuring Custom Search Filters and Examples](https://docs.creatordb.app/api-v3/configuring_advanced_search_filters.md#configuring-custom-cross-platform-creator-filter-search-criteria). |

> [!WARNING]
>
> * When a `creatorId` is no longer available, the request doesn't return an error. It's charged like any search: 1 credit, or 3 credits with `keywords`.
> * Treat `creatorId` as an opaque string. The ID's prefixes, such as `yt`, `ig`, and `tt`, show the platform the record was created from, **not** the current main platform. For example, a `creatorId` such as `yt_UC4-79UOlP48-QNGgCko5p2g` may have Instagram as the main platform.

> [!NOTE]
>
> The `uniqueId` returned for YouTube includes the prefix `@`. For example, @mrbeast. Instagram and TikTok handles returned strip `@`, for example `mrbeast`.

The `data` object also includes three pagination fields:

* `totalResults`: The total number of creators that match your request
* `offset`: The `offset` value used in this request
* `pageSize`: The `pageSize` value used in this request

To get the next page, increase `offset` by `pageSize` and send the request again. Stop when `offset` is greater than or equal to `totalResults`.  If `offset` combined with `pageSize` is less than `totalResults`, there is another page of results. Do not treat a page with fewer rows than `pageSize` as the last page, keep paging until you reach the `totalResults`.

Results are sorted by the `sortBy` field you requested, or by the `creatorDBScore` descending if unspecified. It is not sorted by input order. Since one input can match several creators, matches can land on any page. To find unmatched inputs, keep paging with `offset` and `pageSize`.

`totalResults` is the number of creators matching your filters. It's recounted on every request, so it can change slightly between pages.

To get metrics, audience data, or contact details for an account, take its ID from `platforms` and call the matching platform endpoint, such as [`youtube/performance`](https://docs.creatordb.app/api-reference/youtube/get-performance-information) or [`instagram/contact`](https://docs.creatordb.app/api-reference/instagram/get-contact).

## Cost

Each request is charged once, and the price depends on the filters you use:

| Request | Price |
| - | - |
| Standard search | 1 credit per page, even when no creators match. |
| Search with `keywords` | 3 credits per page, even when no creators match. |
| Search with `email` | 15 credits for each input email address that matches a creator on the returned page. This replaces the page price, and `keywords` doesn't add to it. |

How email lookups are charged:

* Each page is charged separately. If an address's creator shows up on another page, the address is charged again there.
* On one page, each address counts once, even if you entered it twice or it matches several creators.
* An address with no match costs nothing, so a lookup with no matches costs 0 credits.

This endpoint doesn't support `fields` yet. If you send it, it's ignored.

For details, see [API credit usage](https://docs.creatordb.app/api-v3/api-credit-usage.md#creator).

## Limits

| Limit | Maximum |
| - | - |
| Filters per request | 10 |
| Values in an `in` array | 100 |
| Results per page (`pageSize`) | 100 |

## Notes

* Linked accounts come from links on the creators' own profiles and CreatorDB's account mapping, not from name similarity.


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