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

# Submitting Creators

> Add new creators to the CreatorDB database, and understand what happens after they are accepted

## Overview

If a creator is missing from CreatorDB, you can submit them for indexing using platform-specific endpoints, instead of submitting a support ticket. Creator submissions are **free** across all platforms.

| Platform  | Endpoint                         | Accepts                            |
| --------- | -------------------------------- | ---------------------------------- |
| YouTube   | `POST /youtube/submitCreators`   | `channelIds`, `uniqueIds`, or both |
| Instagram | `POST /instagram/submitCreators` | `uniqueIds`                        |
| TikTok    | `POST /tiktok/submitCreators`    | `uniqueIds`                        |

<Warning>
  **Submissions are processed asynchronously.**

  Accepted creators enter a background scraping queue and are **not** immediately queryable. The initial scrape typically takes **1 to 7 calendar days**.

  Calling `/profile` for a pending creator returns a `404 Not Found` response. This is expected behavior, not an API error. For details, see [After a creator is accepted](#after-a-creator-is-accepted).
</Warning>

## Cost

Submitting creators costs 0 credits, regardless of the batch outcome. You are **not charged** when a batch of 100 submitted handles falls into any of the following categories (or a mixture of them):

* New creators awaiting indexing
* Already indexed creators
* Invalid handles

To prevent abuse on free submissions, usage is governed by a daily submission cap rather than credit balance. For details, see [Limits](#limits).

<Note>
  **Brand submissions use different pricing**

  The `/sponsor/submit` endpoint operates under a separate billing model:

  * Brand submissions (`/sponsor/submit`): Require manual human review and **cost 1 credit** per accepted brand.
  * Creator submissions (`/{platform}/submitCreators`): Processed via automated scraping queues and **cost 0 credits**.
</Note>

## Submitting a batch

You can submit between **1 and 100 identifiers** per request. Request payloads with `0` or more than `100` total items return an HTTP `400 Bad Request` (`VALIDATION_ERROR`).

<CodeGroup>
  ```bash YouTube (channel IDs) theme={null}
  curl -X POST "https://apiv3.creatordb.app/youtube/submitCreators" \
    --header 'Content-Type: application/json' \
    --header 'api-key: YOUR_API_KEY' \
    --data '{
      "channelIds": [
        "UCm-X6o81nRsXQTmqpyArkBQ",
        "UCX6OQ3DkcsbYNE6H8uQQuVA"
      ]
    }'
  ```

  ```bash YouTube (handles) theme={null}
  curl -X POST "https://apiv3.creatordb.app/youtube/submitCreators" \
    --header 'Content-Type: application/json' \
    --header 'api-key: YOUR_API_KEY' \
    --data '{ "uniqueIds": ["@mrbeast", "mkbhd"] }'
  ```

  ```bash Instagram theme={null}
  curl -X POST "https://apiv3.creatordb.app/instagram/submitCreators" \
    --header 'Content-Type: application/json' \
    --header 'api-key: YOUR_API_KEY' \
    --data '{ "uniqueIds": ["goodalicia", "@mrbeast"] }'
  ```

  ```bash TikTok theme={null}
  curl -X POST "https://apiv3.creatordb.app/tiktok/submitCreators" \
    --header 'Content-Type: application/json' \
    --header 'api-key: YOUR_API_KEY' \
    --data '{ "uniqueIds": ["charlidamelio", "@khaby.lame"] }'
  ```
</CodeGroup>

On YouTube, you can submit `channelIds`, `uniqueIds` (handles), or both. At least one array must be populated, and the combined count of the two arrays must be between 1 and 100.

## Reading the response

Each submitted identifier gets its own result, so **one request can succeed and fail at the same time**. Inspect `data.results` per entry rather than relying on the top-level `success` field, which is `true` whenever the request was processed — even when some identifiers were rejected.

### Response statuses

| `status`   | Meaning                                                       | What to do                                                      | Credits charged |
| ---------- | ------------------------------------------------------------- | --------------------------------------------------------------- | --------------- |
| `accepted` | New to CreatorDB and queued for scraping.                     | Wait 1 to 7 calendar days for the first scrape before querying. | 0               |
| `done`     | Already in the database. The existing identifier is returned. | Query the creator immediately.                                  | 0               |
| `rejected` | The identifier failed format validation and was not queued.   | Fix the identifier format and resubmit.                         | 0               |

<Note>
  A `done` result is not a failure. It means the creator is already available in the database, so you can query them immediately and bypass the scraping queue.
</Note>

### Example response

```json Instagram theme={null}
{
  "data": {
    "results": [
      {
        "uniqueId": "goodalicia",
        "status": "accepted",
        "existingUniqueId": null
      },
      {
        "uniqueId": "mrbeast",
        "status": "done",
        "existingUniqueId": "mrbeast"
      },
      {
        "uniqueId": "definitely_not_a_real_handle_zzz",
        "status": "rejected",
        "existingUniqueId": null
      }
    ]
  },
  "creditsUsed": 0,
  "creditsAvailable": 99749,
  "traceId": "ig-submit-abc123",
  "timestamp": 1750732453635,
  "errorCode": "",
  "errorDescription": "",
  "success": true
}
```

On YouTube, the duplicate field is `existingChannelId` and each result also echoes the normalized `uniqueId`. On Instagram and TikTok, the duplicate field is `existingUniqueId`.

## Handle normalization

Normalization applies to `uniqueIds` (handles). YouTube `channelIds` are case-sensitive and used as-is. Handles are normalized **before** validation and duplicate checking, and the response echoes the normalized form, the value to use when you later query `/profile` or other endpoints.

Normalization does two things: it strips a leading `@`, and it lowercases the handle. So `@Charli.DAmelio` and `charli.damelio` are the same submission:

| Raw input (`uniqueIds`) | Normalized form  | Deduplicated                     |
| ----------------------- | ---------------- | -------------------------------- |
| `@Charli.DAmelio`       | `charli.damelio` | Yes — treated as the same handle |
| `charli.damelio`        | `charli.damelio` | Yes — treated as the same handle |

## Identifier formats

An identifier that fails these checks is returned as `rejected` rather than failing the whole request.

| Platform              | Format                                                                                                           |
| --------------------- | ---------------------------------------------------------------------------------------------------------------- |
| YouTube `channelIds`  | The `UC` prefix plus 22 characters, 24 in total. Example: `UCm-X6o81nRsXQTmqpyArkBQ`                             |
| YouTube `uniqueIds`   | The channel handle, with or without a leading `@`.                                                               |
| Instagram `uniqueIds` | 1 to 30 characters **before** normalization: letters (a-z, A-Z), digits (0-9), periods (.), and underscores (\_) |
| TikTok `uniqueIds`    | 2 to 24 characters **after** normalization: letters (a-z, A-Z), digits (0-9), periods (.), and underscores (\_)  |

Pass the bare identifier, not a profile URL. A URL fails validation and is returned as `rejected`. For identifier rules that apply across the whole API, see [Introduction](/api-v3/introduction).

## The `notes` parameter is not accepted

The `notes` field, a planned `submitCreators` parameter, was never implemented. The platforms handle it in two ways:

* **YouTube** uses a strict request schema, so sending `notes` returns a `400 VALIDATION_ERROR`.
* **Instagram and TikTok** silently drop it. The request succeeds, but the `notes` value is discarded.

Do not send `notes` on any platform.

## Limits

* **1 to 100 identifiers per request.** Outside this range, the request returns a `400 VALIDATION_ERROR`.
* **Maximum of 10,000 identifiers per API key per UTC day**, counted across all three platforms (YouTube, Instagram, TikTok) together. This cap is independent of your credit balance.
* **Submission can be disabled per key.** If your key has been blocked from submitting, the request returns `403` with `errorCode: "SUBMIT_CREATORS_DISABLED"`. Contact your account manager.

## After a creator is accepted

An `accepted` creator is queued, but not yet indexed in the CreatorDB database. Until the first scrape completes, the creator does not exist for any other endpoint.

<Steps>
  <Step title="Submit a creator">
    If the creator is accepted, the API returns a `status` of `accepted` and a `traceId`. Store both. You will need the `traceId` if you submit a support ticket for this request.
  </Step>

  <Step title="Wait for the first scrape">
    This normally takes 1 to 7 calendar days, depending on queue priority.
  </Step>

  <Step title="Poll creator data">
    Call the `/{platform}/profile` endpoint with the normalized creator identifier from the response. A `404 Not Found` response means the scrape is incomplete. Once the `/{platform}/profile` endpoint returns data, all other endpoints for that creator work too.
  </Step>
</Steps>

If a creator has not appeared after 7 calendar days, contact support ([support@creatordb.app](mailto:support@creatordb.app)) and quote the `traceId` from the original response.

<Note>
  Poll on a schedule you control rather than tightly. Because `/{platform}/profile` is a billable call, a tight polling loop on a queued creator spends credits without returning data.
</Note>

## Related pages

* For credit costs across every endpoint, see [API Credit Usage](/api-v3/api-credit-usage).
* For the error envelope and status codes, see [Error Codes](/api-v3/error-code).