> ## 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 Performance Information
> Retrieve advanced performance information of a specified YouTube creator, including upload activity, subscriber growth, engagement metrics, and video performance.
Optionally pass `fields` in the request body to return only a subset of performance blocks. Requesting a subset bills fractionally, 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 costs work, see [Fractional Costs](/api-v3/fractional-calls).
## OpenAPI
````yaml /api-v3/api-v3.yaml post /youtube/performance
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/performance:
post:
tags:
- YouTube
summary: Get Performance Information
description: >-
Retrieve advanced performance information of a specified YouTube
creator, including upload activity, subscriber growth, engagement
metrics, and video performance.
Optionally pass `fields` in
the request body to return only a subset of performance blocks.
Requesting a subset bills fractionally, 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 costs work, see [Fractional
Costs](/api-v3/fractional-calls).
operationId: getYoutubePerformance
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 performance blocks 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
examples:
- - engagement
- views
responses:
'200':
description: >-
Performance data of the specified YouTube creator returned
successfully.
content:
application/json:
schema:
type: object
properties:
data:
type: object
description: Performance metrics.
properties:
contentCountByDays:
type: object
description: >-
Number of videos published over different time
intervals.
properties:
7d:
type: integer
description: Number of videos published in the past 7 days.
minimum: 0
examples:
- 1
30d:
type: integer
description: Number of videos published in the past 30 days.
minimum: 0
examples:
- 2
90d:
type: integer
description: Number of videos published in the past 90 days.
minimum: 0
examples:
- 2
required:
- 7d
- 30d
- 90d
ranking:
type: object
description: >-
Percentile rankings for various performance metrics,
benchmarked at the global, country, or language level.
A value of `1.0` indicates top 1%, while `0.5`
represents the median.
properties:
totalSubscribers:
type: object
description: Percentile rank of the total subscriber count.
properties:
global:
type: number
description: >-
Percentile rank compared to all creators in
CreatorDB's database.
minimum: 0
maximum: 1
examples:
- 0.9912
country:
type: number
description: >-
Percentile rank among creators from the same
country.
minimum: 0
maximum: 1
examples:
- 0.9986
language:
type: number
description: >-
Percentile rank among creators using the same
primary language.
minimum: 0
maximum: 1
examples:
- 0.9764
required:
- global
- country
- language
avgEngagementRate:
type: object
description: >-
Percentile rank of the average engagement rate for
the last 20 YouTube videos.
properties:
global:
type: number
description: >-
Percentile rank compared to all creators in
CreatorDB's database.
minimum: 0
maximum: 1
examples:
- 0.9912
country:
type: number
description: >-
Percentile rank among creators from the same
country.
minimum: 0
maximum: 1
examples:
- 0.9986
language:
type: number
description: >-
Percentile rank among creators using the same
primary language.
minimum: 0
maximum: 1
examples:
- 0.9764
required:
- global
- country
- language
required:
- totalSubscribers
- avgEngagementRate
videosPerformanceRecent:
type: object
description: >-
Performance metrics of the creator's last 20 YouTube
videos.
properties:
likes:
type: object
properties:
all:
type: integer
description: >-
Total number of likes across the last 20
YouTube videos.
minimum: 0
examples:
- 2944445
avg:
type: integer
description: >-
Average likes per video for the last 20
YouTube videos, rounded to an integer.
minimum: 0
examples:
- 100
median:
type: integer
description: >-
Median number of likes across the last 20
YouTube videos.
minimum: 0
examples:
- 48
min:
type: integer
description: >-
Minimum number of likes across the last 20
YouTube videos.
minimum: 0
examples:
- 20
max:
type: integer
description: >-
Maximum number of likes across the last 20
YouTube videos.
minimum: 0
examples:
- 149
required:
- all
- avg
- median
- min
- max
comments:
type: object
properties:
all:
type: integer
description: >-
Total number of comments across the last 20
YouTube videos.
minimum: 0
examples:
- 2944445
avg:
type: integer
description: >-
Average comments per video for last 20 YouTube
videos, rounded to an integer.
minimum: 0
examples:
- 100
median:
type: integer
description: >-
Median number of comments across the last 20
YouTube videos.
minimum: 0
examples:
- 48
min:
type: integer
description: >-
Minimum number of comments across the last 20
YouTube videos.
minimum: 0
examples:
- 20
max:
type: integer
description: >-
Maximum number of comments across the last 20
YouTube videos.
minimum: 0
examples:
- 149
required:
- all
- avg
- median
- min
- max
views:
type: object
properties:
all:
type: integer
description: >-
Total number of views across the last 20
YouTube videos.
minimum: 0
examples:
- 3599
avg:
type: integer
description: >-
Average views per video for the last 20
YouTube videos, rounded to an integer.
minimum: 0
examples:
- 100
median:
type: integer
description: >-
Median number of views across the last 20
YouTube videos.
minimum: 0
examples:
- 48
min:
type: integer
description: >-
Minimum number of views across the last 20
YouTube videos.
minimum: 0
examples:
- 20
max:
type: integer
description: >-
Maximum number of views across the last 20
YouTube videos.
minimum: 0
examples:
- 149
percentile25:
type: integer
description: >-
The 25th percentile (first quartile) of views
across the last 20 YouTube videos.
minimum: 0
examples:
- 35
percentile75:
type: integer
description: >-
The 75th percentile (third quartile) of views
across the last 20 YouTube videos.
minimum: 0
examples:
- 85
iqr:
type: integer
description: >-
Interquartile range (IQR) of views, calculated
from the 25th to the 75th percentile,
representing the spread of the middle 50%.
minimum: 0
examples:
- 50
required:
- all
- avg
- median
- min
- max
- percentile25
- percentile75
- iqr
length:
type: object
description: Video length in seconds.
properties:
avg:
type: integer
description: >-
Average video length in seconds, rounded to an
integer.
minimum: 0
examples:
- 180
required:
- avg
engagement:
type: object
description: >-
Engagement performance metrics including
engagement rates, per-subscriber statistics, and
consistency analysis.
properties:
avgEngagementRate:
type: number
description: >-
Average engagement rate per video, rounded to
4th decimal place.
- *Engagement Rate = (Likes + Comments +
Views)/ Subscribers*
minimum: 0
examples:
- 0.5201
likesPerSubscriber:
type: number
description: >-
Average likes per subscriber for the last 20
YouTube videos, rounded to 4th decimal place.
minimum: 0
examples:
- 0.1111
commentsPerSubscriber:
type: number
description: >-
Average comments per subscriber for the last
20 YouTube videos, rounded to 4th decimal
place.
minimum: 0
examples:
- 0.1111
viewsPerSubscriber:
type: number
description: >-
Average views per subscriber for the last 20
YouTube videos, rounded to 4th decimal place.
minimum: 0
examples:
- 0.1111
engagementConsistency:
type: object
description: >-
Consistency of engagement performance across
the last 20 YouTube videos.
properties:
cv:
type: number
description: >-
*cv = Standard Deviation of Engagement
Rate/ Mean Engagement Rate*
- The value is rounded to 4th decimal
place.
- Lower values indicate more consistent
performance.
- *A value of `0` indicates insufficient
data.*
minimum: 0
examples:
- 0.1001
medianVsMean:
type: number
description: >-
*medianVsMean = Median Engagement
Rate/ Mean Engagement Rate*
- The value is rounded to 4th decimal
place.
- Values closer to `1` indicate more
consistent performance.
- *A value of `0` indicates insufficient
data.*
minimum: 0
examples:
- 0.9001
topBottomRatio:
type: number
description: >-
*topBottomRatio = avg(Top 3
Engagement)/ avg(Bottom 3 Engagement)*
- The value is rounded to 4th decimal
place.
- Lower ratios indicate more consistent
performance.
- *A value of `0` indicates insufficient
data.*
minimum: 0
examples:
- 1.2001
consistencyScore:
type:
- integer
- 'null'
description: >-
*consistencyScore = 100 -
[(cvScore*weight_cv) +
(topBottomScore*weight_topBottom) +
(medianVsMeanScore*weight_medianVsMean)]*
- The score is rounded to an integer.
- A higher score indicates more stable and
consistent performance.
- If any of the three indicators is `0`,
the `consistencyScore` will be null.
minimum: 0
maximum: 100
examples:
- 63
consistencyLevel:
type: string
enum:
- high
- moderate
- low
- null
description: >-
A qualitative label based on the
`consistencyScore`:
- high: 81 - 100
- moderate: 51 - 80
- low: 0 - 50
- Returns `null` when `consistencyScore`
is `null`.
examples:
- moderate
required:
- cv
- medianVsMean
- topBottomRatio
- consistencyScore
- consistencyLevel
required:
- avgEngagementRate
- likesPerSubscriber
- commentsPerSubscriber
- viewsPerSubscriber
- engagementConsistency
required:
- likes
- comments
- views
- length
- engagement
shortsPerformanceRecent:
type: object
description: >-
Performance metrics of the creator's last 20 YouTube
shorts.
properties:
likes:
type: object
properties:
all:
type: integer
description: >-
Total number of likes across the last 20
YouTube shorts.
minimum: 0
examples:
- 2459
avg:
type: integer
description: >-
Average likes per short for the last 20
YouTube shorts, rounded to an integer.
minimum: 0
examples:
- 100
median:
type: integer
description: >-
Median number of likes across the last 20
YouTube shorts.
minimum: 0
examples:
- 120
min:
type: integer
description: >-
Minimum number of likes across the last 20
YouTube shorts.
minimum: 0
examples:
- 50
max:
type: integer
description: >-
Maximum number of likes across the last 20
YouTube shorts.
minimum: 0
examples:
- 988
required:
- all
- avg
- median
- min
- max
comments:
type: object
properties:
all:
type: integer
description: >-
Total number of comments across the last 20
YouTube shorts.
minimum: 0
examples:
- 2459
avg:
type: integer
description: >-
Average comments per short, rounded to an
integer.
minimum: 0
examples:
- 100
median:
type: integer
description: >-
Median number of comments across the last 20
YouTube shorts.
minimum: 0
examples:
- 120
min:
type: integer
description: >-
Minimum number of comments across the last 20
YouTube shorts.
minimum: 0
examples:
- 50
max:
type: integer
description: >-
Maximum number of comments across the last 20
YouTube shorts.
minimum: 0
examples:
- 988
required:
- all
- avg
- median
- min
- max
views:
type: object
properties:
all:
type: integer
description: >-
Total number of views across the last 20
YouTube shorts.
minimum: 0
examples:
- 2459
avg:
type: integer
description: >-
Average views per short for the last 20
YouTube shorts, rounded to an integer.
minimum: 0
examples:
- 100
median:
type: integer
description: >-
Median number of views across the last 20
YouTube shorts.
minimum: 0
examples:
- 120
min:
type: integer
description: >-
Minimum number of views across the last 20
YouTube shorts.
minimum: 0
examples:
- 50
max:
type: integer
description: >-
Maximum number of views across the last 20
YouTube shorts.
minimum: 0
examples:
- 988
percentile25:
type: integer
description: >-
The 25th percentile (first quartile) of views
across the last 20 YouTube shorts.
minimum: 0
examples:
- 80
percentile75:
type: integer
description: >-
The 75th percentile (third quartile) of views
across the last 20 YouTube shorts.
minimum: 0
examples:
- 250
iqr:
type: integer
description: >-
Interquartile range (IQR) of views, calculated
as the 25th to 75th percentile, representing
the spread of the middle 50%.
minimum: 0
examples:
- 170
required:
- all
- avg
- median
- min
- max
- percentile25
- percentile75
- iqr
length:
type: object
description: Shorts length statistics in seconds.
properties:
avg:
type: integer
description: >-
The average shorts length in seconds, rounded
to an integer.
minimum: 0
examples:
- 180
required:
- avg
engagement:
type: object
description: >-
Engagement performance metrics of shorts including
rates, per-subscriber statistics and consistency
analysis.
properties:
avgEngagementRate:
type: number
description: >-
Average engagement rate per short, rounded to
4th decimal place.
- *Engagement Rate = (Likes + Comments +
Views)/ Subscribers*.
minimum: 0
examples:
- 0.5201
likesPerSubscriber:
type: number
description: >-
Average likes per subscriber for the last 20
YouTube shorts, rounded to 4th decimal place.
minimum: 0
examples:
- 0.1111
commentsPerSubscriber:
type: number
description: >-
Average comments per subscriber for the last
20 YouTube shorts, rounded to 4th decimal
place.
minimum: 0
examples:
- 0.1111
viewsPerSubscriber:
type: number
description: >-
Average views per subscriber for the last 20
YouTube shorts, rounded to 4th decimal place.
minimum: 0
examples:
- 0.1111
engagementConsistency:
type: object
description: >-
Consistency of engagement performance across
the last 20 YouTube shorts.
properties:
cv:
type: number
description: >-
*cv = Standard Deviation of Engagement
Rate/Mean Engagement Rate*
- The value is rounded to 4th decimal
place.
- Lower values indicate more consistent
performance.
- *A value of `0` indicates insufficient
data.*
minimum: 0
examples:
- 0.1001
medianVsMean:
type: number
description: >-
*medianVsMean = Median Engagement
Rate/ Mean Engagement Rate*
- The value is rounded to 4th decimal
place.
- Values closer to `1` indicate more
consistent performance.
- *A value of `0` indicates insufficient
data.*
minimum: 0
examples:
- 0.9001
topBottomRatio:
type: number
description: >-
*topBottomRatio = avg(Top 3
Engagement)/avg(Bottom 3 Engagement)*
- The value is rounded to 4th decimal
place.
- Lower ratios indicate more consistent
performance.
- *A value of `0` indicates insufficient
data.*
minimum: 0
examples:
- 1.2001
consistencyScore:
type:
- integer
- 'null'
description: >-
*consistencyScore = 100 -
[(cvScore\*weight_cv) +
(topBottomScore\*weight_topBottom) +
(medianVsMeanScore\*weight_medianVsMean)]*
- The score is rounded to an integer.
- A higher score indicates more stable and
consistent performance.
- If any of the three indicators is `0`,
the `consistencyScore` will be `null`.
minimum: 0
maximum: 100
examples:
- 63
consistencyLevel:
type: string
enum:
- high
- moderate
- low
- null
description: >-
A qualitative label based on the
`consistencyScore`:
- high: 81 - 100
- moderate: 51 - 80
- low: 0 - 50
- Returns `null` when `consistencyScore`
is `null`.
examples:
- moderate
required:
- cv
- medianVsMean
- topBottomRatio
- consistencyScore
- consistencyLevel
required:
- avgEngagementRate
- likesPerSubscriber
- commentsPerSubscriber
- viewsPerSubscriber
- engagementConsistency
required:
- likes
- comments
- views
- length
- engagement
videosPerformanceAll:
type: object
description: >-
Creator's video performance metrics for the last 800
YouTube videos.
properties:
likes:
type: object
description: Likes statistics for the last 800 YouTube videos.
properties:
all:
type: integer
description: >-
Total number of likes across the last 800
YouTube videos.
minimum: 0
examples:
- 2944445
avg:
type: integer
description: >-
Average likes per video for the last 800
YouTube videos, rounded to an integer.
minimum: 0
examples:
- 100
median:
type: integer
description: >-
Median number of likes across the last 800
YouTube videos.
minimum: 0
examples:
- 48
min:
type: integer
description: >-
Minimum number of likes across the last 800
YouTube videos.
minimum: 0
examples:
- 20
max:
type: integer
description: >-
Maximum number of likes across the last 800
YouTube videos.
minimum: 0
examples:
- 149
required:
- all
- avg
- median
- min
- max
comments:
type: object
description: >-
Comments statistics for the last 800 YouTube
videos.
properties:
all:
type: integer
description: >-
Total number of comments across the last 800
YouTube videos.
minimum: 0
examples:
- 2944445
avg:
type: integer
description: >-
Average comments per video for the last 800
YouTube videos, rounded to an integer.
minimum: 0
examples:
- 100
median:
type: integer
description: >-
Median number of comments across the last 800
YouTube videos.
minimum: 0
examples:
- 48
min:
type: integer
description: >-
Minimum number of comments across the last 800
YouTube videos.
minimum: 0
examples:
- 20
max:
type: integer
description: >-
Maximum number of comments across the last 800
YouTube videos.
minimum: 0
examples:
- 149
required:
- all
- avg
- median
- min
- max
views:
type: object
description: View statistics for the last 800 YouTube videos.
properties:
all:
type: integer
description: >-
Total number of views across the last 800
YouTube videos.
minimum: 0
examples:
- 3599
avg:
type: integer
description: >-
Average views per video for the last 800
YouTube videos, rounded to an integer.
minimum: 0
examples:
- 100
median:
type: integer
description: >-
Median number of views across the last 800
YouTube videos.
minimum: 0
examples:
- 48
min:
type: integer
description: >-
Minimum number of views across the last 800
YouTube videos.
minimum: 0
examples:
- 20
max:
type: integer
description: >-
Maximum number of views across the last 800
YouTube videos.
minimum: 0
examples:
- 149
percentile25:
type: integer
description: >-
The 25th percentile (first quartile) of views
across the last 800 YouTube videos.
minimum: 0
examples:
- 35
percentile75:
type: integer
description: >-
The 75th percentile (third quartile) of views
across the last 800 YouTube videos.
minimum: 0
examples:
- 85
iqr:
type: integer
description: >-
Interquartile range (IQR) of views, calculated
as 25th to 75th percentile, representing the
spread of the middle 50%.
minimum: 0
examples:
- 50
required:
- all
- avg
- median
- min
- max
- percentile25
- percentile75
- iqr
length:
type: object
description: >-
Video length statistics for the last 800 YouTube
videos.
properties:
avg:
type: integer
description: >-
Average video length in seconds, rounded to an
integer.
minimum: 0
examples:
- 180
required:
- avg
engagement:
type: object
description: >-
Engagement metrics for the last 800 YouTube
videos.
properties:
avgEngagementRate:
type: number
description: >-
Average engagement rate per video, rounded to
4th decimal place.
- *Engagement Rate = (Likes + Comments +
Views)/Subscribers*
minimum: 0
examples:
- 0.5201
likesPerSubscriber:
type: number
description: >-
Average likes per subscriber for the last 800
YouTube videos, rounded to 4th decimal place.
minimum: 0
examples:
- 0.1111
commentsPerSubscriber:
type: number
description: >-
Average comments per subscriber for the last
800 YouTube videos, rounded to 4th decimal
place.
minimum: 0
examples:
- 0.1111
viewsPerSubscriber:
type: number
description: >-
Average views per subscriber for the last 800
YouTube videos, rounded to 4th decimal place.
minimum: 0
examples:
- 0.1111
engagementConsistency:
type: object
description: >-
Consistency of engagement performance across
the last 800 YouTube videos.
properties:
cv:
type: number
description: >-
*cv = Standard Deviation of Engagement
Rate/Mean Engagement Rate*
- The value is rounded to 4th decimal
place.
- Lower values indicate more consistent
performance.
- *A value of `0` indicates insufficient
data.*
minimum: 0
examples:
- 0.1001
medianVsMean:
type: number
description: >-
*medianVsMean = Median Engagement
Rate/ Mean Engagement Rate*
- The value is rounded to 4th decimal
place.
- Values closer to `1` indicate more
consistent performance.
- *A value of `0` indicates insufficient
data.*
minimum: 0
examples:
- 0.9001
topBottomRatio:
type: number
description: >-
*topBottomRatio = avg(Top 3
Engagement)/avg(Bottom 3 Engagement)*
- The value is rounded to 4th decimal
place.
- Lower ratios indicate more consistent
performance.
- *A value of `0` indicates insufficient
data.*
minimum: 0
examples:
- 1.2001
consistencyScore:
type:
- integer
- 'null'
description: >-
*consistencyScore = 100 -
[(cvScore\*weight_cv) +
(topBottomScore\*weight_topBottom) +
(medianVsMeanScore\*weight_medianVsMean)]*
- The score is rounded to an integer.
- A higher score indicates more stable and
consistent performance.
- If any of the three indicators is `0`,
the `consistencyScore` will be `null`.
minimum: 0
maximum: 100
examples:
- 63
consistencyLevel:
type: string
enum:
- high
- moderate
- low
- null
description: >-
A qualitative label based on the
`consistencyScore`:
- high: 81 - 100
- moderate: 51 - 80
- low: 0 - 50
- Returns `null` when `consistencyScore`
is `null`.
examples:
- moderate
required:
- cv
- medianVsMean
- topBottomRatio
- consistencyScore
- consistencyLevel
required:
- avgEngagementRate
- likesPerSubscriber
- commentsPerSubscriber
- viewsPerSubscriber
- engagementConsistency
required:
- likes
- comments
- views
- length
- engagement
shortsPerformanceAll:
type: object
description: Performance metrics for the last 800 YouTube shorts.
properties:
likes:
type: object
description: Likes statistics for the last 800 YouTube shorts.
properties:
all:
type: integer
description: >-
Total number of likes across the last 800
YouTube shorts.
minimum: 0
examples:
- 2459
avg:
type: integer
description: >-
Average likes per short, for the last 800
YouTube shorts, rounded to an integer.
minimum: 0
examples:
- 100
median:
type: integer
description: >-
Median number of likes across the last 800
YouTube shorts.
minimum: 0
examples:
- 120
min:
type: integer
description: >-
Minimum number of likes across the last 800
YouTube shorts.
minimum: 0
examples:
- 50
max:
type: integer
description: >-
Maximum number of likes across the last 800
YouTube shorts.
minimum: 0
examples:
- 988
required:
- all
- avg
- median
- min
- max
comments:
type: object
description: >-
Comments statistics for the last 800 YouTube
shorts.
properties:
all:
type: integer
description: >-
Total number of comments across the last 800
YouTube shorts.
minimum: 0
examples:
- 2459
avg:
type: integer
description: >-
Average comments per short for the last 800
YouTube shorts, rounded to an integer.
minimum: 0
examples:
- 100
median:
type: integer
description: >-
Median number of comments across the last 800
YouTube shorts.
minimum: 0
examples:
- 120
min:
type: integer
description: >-
Minimum number of comments across the last 800
YouTube shorts.
minimum: 0
examples:
- 50
max:
type: integer
description: >-
Maximum number of comments across the last 800
YouTube shorts.
minimum: 0
examples:
- 988
required:
- all
- avg
- median
- min
- max
views:
type: object
description: Views statistics for the last 800 YouTube shorts.
properties:
all:
type: integer
description: >-
Total number of views across the last 800
YouTube shorts.
minimum: 0
examples:
- 2459
avg:
type: integer
description: >-
Average views per short for the last 800
YouTube shorts, rounded to an integer.
minimum: 0
examples:
- 100
median:
type: integer
description: >-
Median number of views across the last 800
YouTube shorts.
minimum: 0
examples:
- 120
min:
type: integer
description: >-
Minimum number of views across the last 800
YouTube shorts.
minimum: 0
examples:
- 50
max:
type: integer
description: >-
Maximum number of views across the last 800
YouTube shorts.
minimum: 0
examples:
- 988
percentile25:
type: integer
description: >-
The 25th percentile (first quartile) of views
across the last 800 YouTube shorts.
minimum: 0
examples:
- 80
percentile75:
type: integer
description: >-
The 75th percentile (third quartile) of views
across the last 800 YouTube shorts.
minimum: 0
examples:
- 250
iqr:
type: integer
description: >-
Interquartile range (IQR) of views calculated
as 25th to 75th percentile, representing the
spread of the middle 50%.
minimum: 0
examples:
- 170
required:
- all
- avg
- median
- min
- max
- percentile25
- percentile75
- iqr
length:
type: object
description: Length statistics for the last 800 YouTube shorts.
properties:
avg:
type: integer
description: >-
Average shorts length in seconds, rounded to
an integer.
minimum: 0
examples:
- 180
required:
- avg
engagement:
type: object
description: >-
Engagement metrics for the last 800 YouTube
shorts.
properties:
avgEngagementRate:
type: number
description: >-
The average engagement rate per YouTube short,
rounded to 4th decimal place.
- *Engagement Rate = (Likes + Comments +
Views)/Subscribers*.
minimum: 0
examples:
- 0.5201
likesPerSubscriber:
type: number
description: >-
Average likes per subscriber for the last 800
YouTube shorts, rounded to 4th decimal place.
minimum: 0
examples:
- 0.1111
commentsPerSubscriber:
type: number
description: >-
Average comments per subscriber for the last
800 YouTube shorts, rounded to 4th decimal
place.
minimum: 0
examples:
- 0.1111
viewsPerSubscriber:
type: number
description: >-
Average views per subscriber for the last 800
YouTube shorts, rounded to 4th decimal place.
minimum: 0
examples:
- 0.1111
engagementConsistency:
type: object
description: >-
Consistency of engagement performance across
the last 800 YouTube shorts.
properties:
cv:
type: number
description: >-
*cv = Standard Deviation of Engagement
Rate/Mean Engagement Rate*
- The value is rounded to 4th decimal
place.
- Lower values indicate more consistent
performance.
- *A value of `0` indicates insufficient
data.*
minimum: 0
examples:
- 0.1001
medianVsMean:
type: number
description: >-
*medianVsMean = Median Engagement
Rate/ Mean Engagement Rate*
- The value is rounded to 4th decimal
place.
- Values closer to `1` indicate more
consistent performance.
- *A value of `0` indicates insufficient
data.*
minimum: 0
examples:
- 0.9001
topBottomRatio:
type: number
description: >-
*topBottomRatio = avg(Top 3
Engagement)/avg(Bottom 3 Engagement)*
- The value is rounded to 4th decimal
place.
- Lower ratios indicate more consistent
performance.
- *A value of `0` indicates insufficient
data.*
minimum: 0
examples:
- 1.2001
consistencyScore:
type:
- integer
- 'null'
description: >-
*consistencyScore = 100 -
[(cvScore\*weight_cv) +
(topBottomScore\*weight_topBottom) +
(medianVsMeanScore\*weight_medianVsMean)]*
- The score is rounded to an integer.
- A higher score indicates more stable
and consistent performance.
- If any of the three indicators is `0`,
the `consistencyScore` will be `null`.
minimum: 0
maximum: 100
examples:
- 63
consistencyLevel:
type: string
enum:
- high
- moderate
- low
- null
description: >-
A qualitative label based on the
`consistencyScore`:
- high: 81 - 100
- moderate: 51 - 80
- low: 0 - 50
* Returns `null` when `consistencyScore`
is `null`.
examples:
- moderate
required:
- cv
- medianVsMean
- topBottomRatio
- consistencyScore
- consistencyLevel
required:
- avgEngagementRate
- likesPerSubscriber
- commentsPerSubscriber
- viewsPerSubscriber
- engagementConsistency
required:
- likes
- comments
- views
- length
- engagement
recentVideosGrowth:
type: object
description: >-
Growth metrics for recent YouTube videos across 7, 30,
and 90-day periods.
properties:
g7:
type: object
description: Growth metrics over 7 days.
properties:
avgViews:
type: number
description: >-
Growth rate of average views, rounded to 4th
decimal place.
examples:
- 0.2345
engagementRate:
type: number
description: >-
Growth rate of engagement rate, rounded to 4th
decimal place.
examples:
- 0.0567
required:
- avgViews
- engagementRate
g30:
type: object
description: Growth metrics over 30 days.
properties:
avgViews:
type: number
description: >-
The growth rate of average views, rounded to
4th decimal place.
examples:
- 0.2345
engagementRate:
type: number
description: >-
Growth rate of engagement rate, rounded to 4th
decimal place.
examples:
- 0.0567
required:
- avgViews
- engagementRate
g90:
type: object
description: Growth metrics over 90 days.
properties:
avgViews:
type: number
description: >-
Growth rate of average views, rounded to 4th
decimal place.
examples:
- 0.2345
engagementRate:
type: number
description: >-
Growth rate of engagement rate, rounded to 4th
decimal place.
examples:
- 0.0567
required:
- avgViews
- engagementRate
required:
- g7
- g30
- g90
recentShortsGrowth:
type: object
description: >-
Growth metrics for recent shorts across 7, 30, and
90-day periods.
properties:
g7:
type: object
description: Growth metrics over 7 days.
properties:
avgViews:
type: number
description: >-
Growth rate of average views, rounded to 4th
decimal place.
examples:
- 0.2345
engagementRate:
type: number
description: >-
Growth rate of engagement rate, rounded to 4th
decimal place.
examples:
- 0.0567
required:
- avgViews
- engagementRate
g30:
type: object
description: Growth metrics over 30 days.
properties:
avgViews:
type: number
description: >-
Growth rate of average views, rounded to 4th
decimal place.
examples:
- 0.2345
engagementRate:
type: number
description: >-
Growth rate of engagement rate, rounded to 4th
decimal place.
examples:
- 0.0567
required:
- avgViews
- engagementRate
g90:
type: object
description: Growth metrics over 90 days.
properties:
avgViews:
type: number
description: >-
Growth rate of average views, rounded to 4th
decimal place.
examples:
- 0.2345
engagementRate:
type: number
description: >-
Growth rate of engagement rate, rounded to 4th
decimal place.
examples:
- 0.0567
required:
- avgViews
- engagementRate
required:
- g7
- g30
- g90
required:
- contentCountByDays
- ranking
- videosPerformanceRecent
- shortsPerformanceRecent
- videosPerformanceAll
- shortsPerformanceAll
- recentVideosGrowth
- recentShortsGrowth
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:
contentCountByDays:
7d: 3
30d: 8
90d: 26
ranking:
totalSubscribers:
global: 1
country: 1
language: 1
avgEngagementRate:
global: 0.5279
country: 0.5036
language: 0.4221
videosPerformanceRecent:
likes:
all: 71621680
avg: 3581084
median: 2669037
min: 1300000
max: 22000000
comments:
all: 1174720
avg: 58736
median: 53951
min: 8770
max: 115035
views:
all: 3050115040
avg: 152505752
median: 131558084
min: 56885878
max: 603517253
percentile25: 104827304
percentile75: 149680016
iqr: 44852712
length:
avg: 1167
engagement:
avgEngagementRate: 0.0231
likesPerSubscriber: 0.0077
commentsPerSubscriber: 0.0001
viewsPerSubscriber: 0.3259
engagementConsistency:
cv: 0.4606
medianVsMean: 0.856
topBottomRatio: 2.6884
consistencyScore: 53
consistencyLevel: moderate
shortsPerformanceRecent:
likes:
all: 51069500
avg: 2553475
median: 2059098
min: 463000
max: 6200000
comments:
all: 635020
avg: 31751
median: 14155
min: 5115
max: 186830
views:
all: 3881469200
avg: 194073460
median: 80108228
min: 12298373
max: 968276492
percentile25: 50286890
percentile75: 201918051
iqr: 151631161
length:
avg: 29
engagement:
avgEngagementRate: 0.0207
likesPerSubscriber: 0.0055
commentsPerSubscriber: 0.0001
viewsPerSubscriber: 0.4147
engagementConsistency:
cv: 0.3732
medianVsMean: 1.0541
topBottomRatio: 3.6335
consistencyScore: 53
consistencyLevel: moderate
videosPerformanceAll:
likes:
all: 222423708
avg: 4835298
median: 3400000
min: 1300000
max: 28000000
comments:
all: 4020078
avg: 87393
median: 71759
min: 8770
max: 349397
views:
all: 8897761232
avg: 193429592
median: 165616724
min: 56885878
max: 603517253
percentile25: 130697086
percentile75: 220213535
iqr: 89516449
length:
avg: 1280
engagement:
avgEngagementRate: 0.0249
likesPerSubscriber: 0.0103
commentsPerSubscriber: 0.0002
viewsPerSubscriber: 0.4133
engagementConsistency:
cv: 0.5654
medianVsMean: 0.8656
topBottomRatio: 4.6788
consistencyScore: 47
consistencyLevel: low
shortsPerformanceAll:
likes:
all: 1650228640
avg: 10313929
median: 8150000
min: 461000
max: 57000000
comments:
all: 5172480
avg: 32328
median: 17060
min: 2772
max: 822627
views:
all: 60515376800
avg: 378221105
median: 338464804
min: 6532098
max: 1692388343
percentile25: 136813142
percentile75: 537217514
iqr: 400404372
length:
avg: 31
engagement:
avgEngagementRate: 0.0279
likesPerSubscriber: 0.022
commentsPerSubscriber: 0.0001
viewsPerSubscriber: 0.8082
engagementConsistency:
cv: 0.4515
medianVsMean: 0.9376
topBottomRatio: 14.6975
consistencyScore: 41
consistencyLevel: low
recentVideosGrowth:
g7:
avgViews: 0.0158
engagementRate: -0.0156
g30:
avgViews: -0.0063
engagementRate: -0.0189
g90:
avgViews: 0.0952
engagementRate: -0.1305
recentShortsGrowth:
g7:
avgViews: 0.0342
engagementRate: 0.0002
g30:
avgViews: 0.4128
engagementRate: -0.0281
g90:
avgViews: 0.2758
engagementRate: -0.2429
traceId: 3d69e43ce36749693badd422e38ccc28
timestamp: 1771887295991
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
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/performance" \
-H "Content-Type: application/json" \
-H "api-key: " \
-d '{ "channelId": "UCX6OQ3DkcsbYNE6H8uQQuVA", "fields": ["engagement"] }'
components:
securitySchemes:
ApiKeyAuth:
type: apiKey
description: The valid CreatorDB API key for authentication.
name: api-key
in: header
````