Submitting Creators

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`

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.

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.

Brand submissions use different pricingThe /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.

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

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"
    ]
  }'

curl -X POST "https://apiv3.creatordb.app/youtube/submitCreators" \
  --header 'Content-Type: application/json' \
  --header 'api-key: YOUR_API_KEY' \
  --data '{ "uniqueIds": ["@mrbeast", "mkbhd"] }'

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

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"] }'

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
`accepted`	New to CreatorDB and queued for scraping.	Wait 1 to 7 calendar days for the first scrape before querying.
`done`	Already in the database. The existing identifier is returned.	Query the creator immediately.
`rejected`	The identifier failed format validation and was not queued.	Fix the identifier format and resubmit.

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.

Example response

Instagram

{
  "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.

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.

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.

Wait for the first scrape

This normally takes 1 to 7 calendar days, depending on queue priority.

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.

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

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.

For credit costs across every endpoint, see API Credit Usage.
For the error envelope and status codes, see Error Codes.

Getting Started

User Guides

API Endpoints

Filter Value References

Troubleshooting and FAQs

Overview

Cost

Submitting a batch

Reading the response

Response statuses

Example response

Handle normalization

Identifier formats

The `notes` parameter is not accepted

Limits

After a creator is accepted

​Overview

​Cost

​Submitting a batch

​Reading the response

​Response statuses

​Example response

​Handle normalization

​Identifier formats

​The notes parameter is not accepted

​Limits

​After a creator is accepted

​Related pages

Overview

Cost

Submitting a batch

Reading the response

Response statuses

Example response

Handle normalization

Identifier formats

The `notes` parameter is not accepted

Limits

After a creator is accepted

Related pages