> ## 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.
# 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](/api-v3/fractional-calls).
## OpenAPI
````yaml /api-v3/api-v3.yaml post /youtube/audience
openapi: 3.1.0
info:
version: 1.0.0
title: CreatorDB Headless API V3
description: '# CreatorDB Headless API V3'
contact:
name: CreatorDB
url: https://www.creatordb.app
email: support@creatordb.app
license:
url: http://www.apache.org/licenses/LICENSE-2.0.html
name: Apache 2.0
servers:
- url: https://apiv3.creatordb.app
description: Production Environment (CreatorDB Headless API V3)
security:
- ApiKeyAuth: []
tags:
- name: Brand
description: Brand analysis endpoints including sponsor search and brand reports.
- name: Facebook
description: Facebook creator data endpoints with metrics and search capabilities.
- name: General Operations
description: >-
General-purpose endpoints such as API status, content retrieval, and
cross-platform operations.
- name: Instagram
description: >-
Instagram creator data endpoints with metrics and advanced search
capabilities.
- name: Niches
description: >-
Niche-related endpoints for content category analysis and related
searches.
- name: Threads
description: Threads creator data endpoints with basic metrics and historical data.
- name: TikTok
description: >-
TikTok creator data endpoints with metrics and advanced search
functionality.
- name: Topic
description: Topic-based analysis and reporting endpoints for content categorization.
- name: YouTube
description: >-
YouTube creator data endpoints including basic metrics, historical data,
and detailed analytics.
paths:
/youtube/audience:
post:
tags:
- YouTube
summary: Get Audience Demographics
description: >-
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](/api-v3/fractional-calls).
operationId: getYoutubeAudience
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- channelId
properties:
channelId:
type: string
description: Unique channel ID.
pattern: ^UC[a-zA-Z0-9_-]{22}$
minLength: 1
maxLength: 50
examples:
- UCBR8-60-B28hp2BmDPdntcQ
fields:
type: array
description: >-
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.
items:
type: string
responses:
'200':
description: YouTube audience demographic data returned successfully.
content:
application/json:
schema:
type: object
properties:
data:
type: object
description: Returned audience demographic data of the YouTube channel.
properties:
audienceLocations:
type: array
description: >-
Country locations of the audience, sorted by
descending share.
examples:
- - country: USA
share: 0.5511
- country: GBR
share: 0.1313
- country: CAN
share: 0.0501
items:
type: object
description: Country distribution of the audience.
properties:
country:
type: string
description: >-
The country in **ISO 3166-1 alpha-3** format.
For details, see [Country
Codes](http://docs.creatordb.app/api-v2/country-code).
examples:
- USA
share:
type: number
description: >-
Proportion of audience from that country,
rounded to 4th decimal place.
examples:
- 0.5511
required:
- country
- share
audienceGender:
type: object
description: Gender distribution of the audience.
properties:
maleRatio:
type: number
description: >-
Proportion of male audience, rounded to 4th
decimal place.
examples:
- 0.5233
femaleRatio:
type: number
description: >-
Proportion of female audience, rounded to 4th
decimal place.
examples:
- 0.4412
required:
- maleRatio
- femaleRatio
examples:
- maleRatio: 0.5233
femaleRatio: 0.4412
audienceAvgAge:
type: integer
description: Average age of the audience, rounded to an integer.
examples:
- 30
audienceAgeBreakdown:
type: array
description: Distribution of the audience by age range.
examples:
- - ageRange: 13-17
share: 0.0123
- ageRange: 18-24
share: 0.1871
- ageRange: 25-34
share: 0.2818
- ageRange: 35-44
share: 0.2025
- ageRange: 45-54
share: 0.1398
- ageRange: 55-64
share: 0.1
- ageRange: 65+
share: 0.0765
items:
type: object
description: Age range distribution of the audience.
properties:
ageRange:
type: string
enum:
- 13-17
- 18-24
- 25-34
- 35-44
- 45-54
- 55-64
- 65+
description: >-
Age group.
Accepted values: `13-17`,
`18-24`, `25-34`, `35-44`, `45-54`, `55-64`,
`65+`
examples:
- 25-34
share:
type: number
description: >-
Percentage of audience in a specific age group,
rounded to 4th decimal place.
examples:
- 0.0123
required:
- ageRange
- share
required:
- audienceLocations
- audienceGender
- audienceAvgAge
- audienceAgeBreakdown
creditsUsed:
type: integer
description: Number of API credits consumed by this request.
examples:
- 1
creditsAvailable:
type: integer
description: Number of API credits remaining.
examples:
- -1
traceId:
type: string
description: Unique trace ID for each request.
examples:
- f8e4a3b2c1d0e9f8a7b6c5d4e3f2a1b0
timestamp:
type: integer
description: >-
Time the response was generated, represented as a Unix
timestamp in milliseconds.
examples:
- 1750732453635
errorCode:
type: string
description: >-
Error code returned if the request fails. Empty if the
request is successful.
examples:
- ''
errorDescription:
type: string
description: >-
Description of the error. Empty if the request is
successful.
examples:
- ''
success:
type: boolean
description: '`true` if the request is successful.'
examples:
- true
required:
- data
- traceId
- timestamp
- errorCode
- errorDescription
- success
- creditsUsed
- creditsAvailable
examples:
default:
value:
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
'400':
description: Validation error.
content:
application/json:
schema:
type: object
title: ValidationErrorResponse
properties:
success:
const: false
error:
type: string
message:
type: string
timestamp:
type: integer
required:
- success
- error
- message
- timestamp
examples:
missing identifier:
summary: No identifier provided
value:
success: false
error: VALIDATION_ERROR
message: 'Missing required identifier: ''channelId'' or ''uniqueId''.'
timestamp: 1770099403116
invalid channelId:
summary: Invalid channelId format
value:
success: false
error: VALIDATION_ERROR
message: >-
Invalid 'channelId' format. YouTube channel IDs must start
with 'UC' followed by 22 characters.
timestamp: 1770099403116
'429':
description: Exceeded quota or rate limit.
content:
application/json:
schema:
type: object
title: QuotaErrorResponse
description: Quota error response format.
properties:
success:
const: false
error:
type: string
message:
type: string
remainingPlanCredit:
type: number
required:
- success
- error
- message
- remainingPlanCredit
examples:
rate limit:
summary: Rate limit exceeded
value:
success: false
error: RATE_LIMIT_EXCEEDED
message: Too many requests. Please try again later.
quota exceeded:
summary: Credit quota exceeded
value:
success: false
error: QUOTA_EXCEEDED
message: Not enough credits to complete this request.
security:
- ApiKeyAuth: []
servers:
- url: https://apiv3.creatordb.app
description: Production Environment (CreatorDB Headless API V3)
x-codeSamples:
- lang: bash
label: cURL
source: |
curl -X POST "https://apiv3.creatordb.app/youtube/audience" \
-H "Content-Type: application/json" \
-H "api-key: " \
-d '{ "channelId": "UCX6OQ3DkcsbYNE6H8uQQuVA" }'
components:
securitySchemes:
ApiKeyAuth:
type: apiKey
description: The valid CreatorDB API key for authentication.
name: api-key
in: header
````