YouTube

Get Audience Demographics

Retrieve audience demographic insights for a specified YouTube creator, including country distribution, gender breakdown, and age composition. This endpoint provides detailed audience analytics to help understand creator reach, evaluate audience alignment, and support data‑driven influencer selection and campaign targeting.

Optionally pass fields in the request body to return only a subset of demographic fields. You are billed for the fields you request, capped at the full-bundle price. Fractional calls must be enabled on your API key. Otherwise, a request that includes fields returns a 400 error (FractionalCallsNotEnabled). Per-field costs are not published yet. For how fractional calls work, see Fractional Calls.

POST

youtube

audience

cURL

curl -X POST "https://apiv3.creatordb.app/youtube/audience" \
  -H "Content-Type: application/json" \
  -H "api-key: <YOUR_API-KEY_HERE>" \
  -d '{ "channelId": "UCX6OQ3DkcsbYNE6H8uQQuVA" }'

const options = {
  method: 'POST',
  headers: {'api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({channelId: '<string>', fields: ['<string>']})
};

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

import requests

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

payload = {
    "channelId": "<string>",
    "fields": ["<string>"]
}
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/audience",
  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([
    'channelId' => '<string>',
    'fields' => [
        '<string>'
    ]
  ]),
  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/audience")

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  \"channelId\": \"<string>\",\n  \"fields\": [\n    \"<string>\"\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/audience"

	payload := strings.NewReader("{\n  \"channelId\": \"<string>\",\n  \"fields\": [\n    \"<string>\"\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/audience")
  .header("api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"channelId\": \"<string>\",\n  \"fields\": [\n    \"<string>\"\n  ]\n}")
  .asString();

{
  "data": {
    "audienceLocations": [
      {
        "country": "USA",
        "share": 0.7795
      },
      {
        "country": "GBR",
        "share": 0.0716
      },
      {
        "country": "CAN",
        "share": 0.0433
      }
    ],
    "audienceGender": {
      "maleRatio": 0.5833,
      "femaleRatio": 0.4167
    },
    "audienceAvgAge": 35,
    "audienceAgeBreakdown": [
      {
        "ageRange": "13-17",
        "share": 0.0328
      },
      {
        "ageRange": "18-24",
        "share": 0.2022
      },
      {
        "ageRange": "25-34",
        "share": 0.2988
      },
      {
        "ageRange": "35-44",
        "share": 0.2585
      },
      {
        "ageRange": "45-54",
        "share": 0.1274
      },
      {
        "ageRange": "55-64",
        "share": 0.0532
      },
      {
        "ageRange": "65+",
        "share": 0.0271
      }
    ]
  },
  "creditsUsed": 1,
  "creditsAvailable": -1,
  "traceId": "fd5e5b27302d80f119671196c628e094",
  "timestamp": 1767924063347,
  "errorCode": "",
  "errorDescription": "",
  "success": true
}

Authorizations

api-key

string

header

required

The valid CreatorDB API key for authentication.

Body

application/json

channelId

string

required

Unique channel ID.

Required string length: 1 - 50

Pattern: ^UC[a-zA-Z0-9_-]{22}$

Example:

"UCBR8-60-B28hp2BmDPdntcQ"

fields

string[]

Subset of demographic fields to return. Omit or pass an empty array to return the full response at the full-bundle price. Per-field costs are not published yet.

Response

YouTube audience demographic data returned successfully.

data

object

required

Returned audience demographic data of the YouTube channel.

Show child attributes

creditsUsed

integer

required

Number of API credits consumed by this request.

Example:

1

creditsAvailable

integer

required

Number of API credits remaining.

Example:

-1

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

Last modified on July 28, 2026

Search ContentSearch for YouTube content (videos, shorts, streams) across all creators in the CreatorDB database using content-level and creator-level filters. Enables discovery of specific content by performance metrics, hashtags, sponsorship status, and more. By default, the `contentList` is sorted by `publishTime` descending (newest first). Custom sorting can be applied using the `sortBy` parameter.

⌘I

cURL

curl -X POST "https://apiv3.creatordb.app/youtube/audience" \
  -H "Content-Type: application/json" \
  -H "api-key: <YOUR_API-KEY_HERE>" \
  -d '{ "channelId": "UCX6OQ3DkcsbYNE6H8uQQuVA" }'

const options = {
  method: 'POST',
  headers: {'api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({channelId: '<string>', fields: ['<string>']})
};

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

import requests

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

payload = {
    "channelId": "<string>",
    "fields": ["<string>"]
}
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/audience",
  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([
    'channelId' => '<string>',
    'fields' => [
        '<string>'
    ]
  ]),
  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/audience")

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  \"channelId\": \"<string>\",\n  \"fields\": [\n    \"<string>\"\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/audience"

	payload := strings.NewReader("{\n  \"channelId\": \"<string>\",\n  \"fields\": [\n    \"<string>\"\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/audience")
  .header("api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"channelId\": \"<string>\",\n  \"fields\": [\n    \"<string>\"\n  ]\n}")
  .asString();

{
  "data": {
    "audienceLocations": [
      {
        "country": "USA",
        "share": 0.7795
      },
      {
        "country": "GBR",
        "share": 0.0716
      },
      {
        "country": "CAN",
        "share": 0.0433
      }
    ],
    "audienceGender": {
      "maleRatio": 0.5833,
      "femaleRatio": 0.4167
    },
    "audienceAvgAge": 35,
    "audienceAgeBreakdown": [
      {
        "ageRange": "13-17",
        "share": 0.0328
      },
      {
        "ageRange": "18-24",
        "share": 0.2022
      },
      {
        "ageRange": "25-34",
        "share": 0.2988
      },
      {
        "ageRange": "35-44",
        "share": 0.2585
      },
      {
        "ageRange": "45-54",
        "share": 0.1274
      },
      {
        "ageRange": "55-64",
        "share": 0.0532
      },
      {
        "ageRange": "65+",
        "share": 0.0271
      }
    ]
  },
  "creditsUsed": 1,
  "creditsAvailable": -1,
  "traceId": "fd5e5b27302d80f119671196c628e094",
  "timestamp": 1767924063347,
  "errorCode": "",
  "errorDescription": "",
  "success": true
}

Getting Started

User Guides

API Endpoints

Filter Value References

Troubleshooting and FAQs

Get Audience Demographics

Authorizations

Body

Response