YouTube

Submit Creators

Submit new YouTube creators to the CreatorDB database for indexing. You can identify creators by channel ID, by handle, or both in one request. Accepted creators enter a processing queue and become available through the other YouTube endpoints after their first scrape. Submissions are free of charge. You can submit up to 10,000 identifiers per API key per UTC day. This limit is shared across the YouTube, Instagram, and TikTok submit endpoints. For details, see API Credit Usage. Send bare identifiers, not profile URLs. Handles work with or without the @ prefix. A URL doesn’t cause the request to fail. Instead, the request succeeds and the response marks that entry with status rejected, so check the status of every entry.

POST

youtube

submitCreators

cURL

curl -X POST "https://apiv3.creatordb.app/youtube/submitCreators" \
  -H "Content-Type: application/json" \
  -H "api-key: <YOUR_API_KEY_HERE>" \
  -d '{ "channelIds": ["UCm-X6o81nRsXQTmqpyArkBQ"], "uniqueIds": ["@mrbeast"] }'

const options = {
  method: 'POST',
  headers: {'api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    channelIds: ['UCm-X6o81nRsXQTmqpyArkBQ', 'UCX6OQ3DkcsbYNE6H8uQQuVA'],
    uniqueIds: ['@mrbeast', 'youtube']
  })
};

fetch('https://apiv3.creatordb.app/youtube/submitCreators', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://apiv3.creatordb.app/youtube/submitCreators"

payload = {
    "channelIds": ["UCm-X6o81nRsXQTmqpyArkBQ", "UCX6OQ3DkcsbYNE6H8uQQuVA"],
    "uniqueIds": ["@mrbeast", "youtube"]
}
headers = {
    "api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://apiv3.creatordb.app/youtube/submitCreators",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'channelIds' => [
        'UCm-X6o81nRsXQTmqpyArkBQ',
        'UCX6OQ3DkcsbYNE6H8uQQuVA'
    ],
    'uniqueIds' => [
        '@mrbeast',
        'youtube'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

require 'uri'
require 'net/http'

url = URI("https://apiv3.creatordb.app/youtube/submitCreators")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"channelIds\": [\n    \"UCm-X6o81nRsXQTmqpyArkBQ\",\n    \"UCX6OQ3DkcsbYNE6H8uQQuVA\"\n  ],\n  \"uniqueIds\": [\n    \"@mrbeast\",\n    \"youtube\"\n  ]\n}"

response = http.request(request)
puts response.read_body

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://apiv3.creatordb.app/youtube/submitCreators"

	payload := strings.NewReader("{\n  \"channelIds\": [\n    \"UCm-X6o81nRsXQTmqpyArkBQ\",\n    \"UCX6OQ3DkcsbYNE6H8uQQuVA\"\n  ],\n  \"uniqueIds\": [\n    \"@mrbeast\",\n    \"youtube\"\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://apiv3.creatordb.app/youtube/submitCreators")
  .header("api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"channelIds\": [\n    \"UCm-X6o81nRsXQTmqpyArkBQ\",\n    \"UCX6OQ3DkcsbYNE6H8uQQuVA\"\n  ],\n  \"uniqueIds\": [\n    \"@mrbeast\",\n    \"youtube\"\n  ]\n}")
  .asString();

{
  "data": {
    "results": [
      {
        "channelId": "<string>",
        "uniqueId": "<string>",
        "status": "accepted",
        "existingChannelId": "<string>"
      }
    ]
  },
  "creditsUsed": 0,
  "creditsAvailable": 975,
  "planCreditsAvailable": 900,
  "purchasedCreditsAvailable": 75,
  "traceId": "f8e4a3b2c1d0e9f8a7b6c5d4e3f2a1b0",
  "timestamp": 1750732453635,
  "errorCode": "",
  "errorDescription": "",
  "success": true,
  "keyCreditsAvailable": 4975
}

Authorizations

api-key

string

header

required

The valid CreatorDB API key for authentication.

Body

application/json

channelIds

string[]

YouTube channel IDs to submit. Each ID is 24 characters and starts with UC. Can be combined with uniqueIds (handles). channelIds and uniqueIds together must contain 1 to 100 identifiers.

Maximum array length: 100

Example:

[
  "UCm-X6o81nRsXQTmqpyArkBQ",
  "UCX6OQ3DkcsbYNE6H8uQQuVA"
]

uniqueIds

string[]

YouTube channel handles to submit. Handles are case-insensitive, and the leading @ is optional, so @MrBeast and mrbeast are the same handle. Leading and trailing whitespace is trimmed. Each handle is up to 30 characters and can contain letters, digits, periods (.), underscores (_), and hyphens (-). Can be combined with channelIds. channelIds and uniqueIds together must contain 1 to 100 identifiers.

Maximum array length: 100

Example:

["@mrbeast", "youtube"]

Response

200 - application/json

Returns the indexing status for each submitted creator.

data

object

required

Show child attributes

creditsUsed

number

required

Number of API credits consumed by this request.

Example:

0

creditsAvailable

number

required

Number of API credits remaining. Returns -1 if the quota is unlimited. Equals planCreditsAvailable plus purchasedCreditsAvailable.

Example:

975

planCreditsAvailable

number

required

Remaining plan credits after this request, in credits.

Example:

900

purchasedCreditsAvailable

number

required

Remaining purchased-bucket credits after this request, in display units.

Example:

75

traceId

string

required

Unique trace ID for each request.

Example:

"f8e4a3b2c1d0e9f8a7b6c5d4e3f2a1b0"

timestamp

integer

required

Time the response was generated, represented as a Unix timestamp in milliseconds.

Example:

1750732453635

errorCode

string

required

Error code returned if the request fails. Empty if the request is successful.

Example:

""

errorDescription

string

required

Description of the error. Empty if the request is successful.

Example:

""

success

boolean

required

true if the request is successful.

Example:

true

keyCreditsAvailable

number

Remaining credits this API key can spend after this request, before reaching its spend limit. Present only when the key has a spend limit.

Example:

4975

⌘I

cURL

curl -X POST "https://apiv3.creatordb.app/youtube/submitCreators" \
  -H "Content-Type: application/json" \
  -H "api-key: <YOUR_API_KEY_HERE>" \
  -d '{ "channelIds": ["UCm-X6o81nRsXQTmqpyArkBQ"], "uniqueIds": ["@mrbeast"] }'

const options = {
  method: 'POST',
  headers: {'api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    channelIds: ['UCm-X6o81nRsXQTmqpyArkBQ', 'UCX6OQ3DkcsbYNE6H8uQQuVA'],
    uniqueIds: ['@mrbeast', 'youtube']
  })
};

fetch('https://apiv3.creatordb.app/youtube/submitCreators', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://apiv3.creatordb.app/youtube/submitCreators"

payload = {
    "channelIds": ["UCm-X6o81nRsXQTmqpyArkBQ", "UCX6OQ3DkcsbYNE6H8uQQuVA"],
    "uniqueIds": ["@mrbeast", "youtube"]
}
headers = {
    "api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://apiv3.creatordb.app/youtube/submitCreators",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'channelIds' => [
        'UCm-X6o81nRsXQTmqpyArkBQ',
        'UCX6OQ3DkcsbYNE6H8uQQuVA'
    ],
    'uniqueIds' => [
        '@mrbeast',
        'youtube'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

require 'uri'
require 'net/http'

url = URI("https://apiv3.creatordb.app/youtube/submitCreators")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"channelIds\": [\n    \"UCm-X6o81nRsXQTmqpyArkBQ\",\n    \"UCX6OQ3DkcsbYNE6H8uQQuVA\"\n  ],\n  \"uniqueIds\": [\n    \"@mrbeast\",\n    \"youtube\"\n  ]\n}"

response = http.request(request)
puts response.read_body

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://apiv3.creatordb.app/youtube/submitCreators"

	payload := strings.NewReader("{\n  \"channelIds\": [\n    \"UCm-X6o81nRsXQTmqpyArkBQ\",\n    \"UCX6OQ3DkcsbYNE6H8uQQuVA\"\n  ],\n  \"uniqueIds\": [\n    \"@mrbeast\",\n    \"youtube\"\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://apiv3.creatordb.app/youtube/submitCreators")
  .header("api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"channelIds\": [\n    \"UCm-X6o81nRsXQTmqpyArkBQ\",\n    \"UCX6OQ3DkcsbYNE6H8uQQuVA\"\n  ],\n  \"uniqueIds\": [\n    \"@mrbeast\",\n    \"youtube\"\n  ]\n}")
  .asString();

{
  "data": {
    "results": [
      {
        "channelId": "<string>",
        "uniqueId": "<string>",
        "status": "accepted",
        "existingChannelId": "<string>"
      }
    ]
  },
  "creditsUsed": 0,
  "creditsAvailable": 975,
  "planCreditsAvailable": 900,
  "purchasedCreditsAvailable": 75,
  "traceId": "f8e4a3b2c1d0e9f8a7b6c5d4e3f2a1b0",
  "timestamp": 1750732453635,
  "errorCode": "",
  "errorDescription": "",
  "success": true,
  "keyCreditsAvailable": 4975
}

Getting Started

User Guides

API Endpoints

Filter Value References

Troubleshooting and FAQs

Submit Creators

Authorizations

Body

Response