> ## 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 YouTube historical data > Get the basic metrics and historical data of a creator's YouTube account. ## OpenAPI ````yaml /api-v2/api-v2.yaml get /youtubeHistory openapi: 3.1.0 info: version: '2' title: CreatorDB Headless APIService description: >- Generated from swaggerComponentIndex.json by core-types-json-schema (https://github.com/grantila/core-types-json-schema). Use OpenAPI 3.1.0 version with direct JSON Schema support termsOfService: https://www.creatordb.app 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 x-id: indexForSwagger.yaml servers: - url: https://dev.creatordb.app/v2 description: CreatorDB API Endpoint - prod version security: [] tags: - name: General Operations description: >- General-purpose endpoints such as API status, content retrieval, and cross-platform operations - name: YouTube description: >- YouTube creator data endpoints including basic metrics, historical data, and detailed analytics - name: Instagram description: >- Instagram creator data endpoints with metrics and advanced search capabilities - name: TikTok description: >- TikTok creator data endpoints with metrics and advanced search functionality - name: Threads description: Threads creator data endpoints with basic metrics and historical data - name: Facebook description: Facebook creator data endpoints with metrics and search capabilities - name: Topic description: Topic-based analysis and reporting endpoints for content categorization - name: Brand description: Brand analysis endpoints including sponsor search and brand reports - name: Niches description: Niche-related endpoints for content category analysis and related searches paths: /youtubeHistory: get: tags: - YouTube summary: Get YouTube historical data description: >- Get the basic metrics and historical data of a creator's YouTube account. operationId: getYoutubeHistory parameters: - name: apiId in: header description: '' required: true schema: type: string examples: - LE6DPZQkR3TQShxofXoD2j8qCBu1-f0jti665m1t50dwDD12W - name: youtubeId in: query description: '' required: true schema: type: string examples: - UCm-X6o81nRsXQTmqpyArkBQ responses: '200': description: OK content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/BasicYoutubeAndHistoryResult' quotaUsed: type: number description: API credits that were used to make this call. quotaUsedTotal: type: number description: Total API credits used since the last billing cycle. remainingPlanCredit: type: number description: >- The number of remaining free API credits that come with your subscription plan. These API credits are renewed every billing cycle. remainingPrepurchasedCredit: type: number description: >- The number of remaining extra purchased API credits. These API credits do not expire until used. timestamp: type: number description: >- Unix timestamp of the call request that the server received. error: type: string description: Errors that occurred during the API call. success: type: boolean description: It is TRUE when the call is successful. examples: default: value: data: basicYoutube: youtubeId: UCm-X6o81nRsXQTmqpyArkBQ youtubeName: Flamingo displayId: '@flamingo' instagramId: albertsstuff tiktokId: '' avatar: >- https://yt3.googleusercontent.com/7cF22TRiceqQr2Cro_X4uhRVnwCdOa2HXiwdBGPnUEqJDuCyr2CykDfDw2rCWjbjaHEdTMUC=s900-c-k-c0x00ffffff-no-rj hasEmail: true subscribers: 13900000 views: 12002736149 country: USA lang: eng createDate: 1499184000000 lastUploadTime: 1755142212000 links: - title: Instagram url: https://www.instagram.com/albertsstuff/ - title: The Shop url: http://flimflam.shop/ - title: Business email url: flamingo@ellify.com hashtags: - '#starrailsimulator' - '#honkaistarrail' - '#sponsored' mainCategory: Gaming topicIds: - id_freegames_Gaming - id_rpg_Gaming - id_roblox_Gaming nicheIds: - id_roblox_Gaming - id_funny_Gaming - id_poppyplaytime_Gaming avgLength1Y: 612 avgLikes1Y: 80970 avgComments1Y: 6611 avgSelfCommentRatio1Y: 0.02129629629629627 avgCommentLikeRatio1Y: 0.0012345679012345679 avgCommentReplyRatio1Y: 0.0021604938271604936 avgViews1Y: 2332262 engageRate1Y: 0.03755141478648009 avgLengthR20: 801.5 avgLikesR20: 79945 avgCommentsR20: 7517 avgSelfCommentRatioR20: 0.02222222222222222 avgCommentLikeRatioR20: 0 avgCommentReplyRatioR20: 0.005555555555555556 avgViewsR20: 2297082 engageRateR20: 0.038074757313463874 gRateSubscribers: 0.022058823529411766 gRateViews: 0.008608394749283115 gRateAvgViewsR20: 0.5715348397137289 gRateEngageRateR20: -0.24690527845279533 recentVideos: - uploadDate: 1755142212000 videoId: FbCF_H4ZD64 length: 873 title: I hosted an ADMIN ABUSE on GROW A GARDEN likes: 153000 comments: 15182 selfCommentRatio: 0 commentLikeRatio: 0 commentReplyRatio: 0 views: 5009695 engageRate: 0.03357130523914131 category: Gaming lang: eng isPaidPromote: false isStreaming: false isShorts: false hashtags: [] - uploadDate: 1754966320000 videoId: rqKF4lzzMT0 length: 551 title: Roblox won’t stop BANNING me. likes: 89000 comments: 9190 selfCommentRatio: 0.05 commentLikeRatio: 0 commentReplyRatio: 0 views: 1898329 engageRate: 0.05172443765016496 category: Gaming lang: jav isPaidPromote: false isStreaming: false isShorts: false hashtags: [] - uploadDate: 1754797869000 videoId: eHnzGYHEdO0 length: 572 title: ROBLOX OP ADMIN IN STEAL A BRAINROT likes: 66000 comments: 8527 selfCommentRatio: 0.05 commentLikeRatio: 0 commentReplyRatio: 0 views: 2034093 engageRate: 0.03663893440467078 category: Gaming lang: nld isPaidPromote: false isStreaming: false isShorts: false hashtags: [] histories: - timestamp: 1755360000000 subscribers: 13900000 likes: 13117000 comments: 1070915 views: 12002736149 avgLength1Y: 612 avgLikes1Y: 80970 avgComments1Y: 6611 avgSelfCommentRatio1Y: 0.02129629629629627 avgCommentLikeRatio1Y: 0.0012345679012345679 avgCommentReplyRatio1Y: 0.0021604938271604936 avgViews1Y: 2332262 engageRate1Y: 0.03755141478648009 avgLengthR20: 801.5 avgLikesR20: 79945 avgCommentsR20: 7517 avgSelfCommentRatioR20: 0.02222222222222222 avgCommentLikeRatioR20: 0 avgCommentReplyRatioR20: 0.005555555555555556 avgViewsR20: 2297082 engageRateR20: 0.038074757313463874 - timestamp: 1755187200000 subscribers: 13900000 likes: 13050000 comments: 1069620 views: 11994640894 avgLength1Y: 612 avgLikes1Y: 80556 avgComments1Y: 6603 avgSelfCommentRatio1Y: 0.02129629629629627 avgCommentLikeRatio1Y: 0.0012345679012345679 avgCommentReplyRatio1Y: 0.0021604938271604936 avgViews1Y: 2308133 engageRate1Y: 0.03776133314230006 avgLengthR20: 779.7777777777778 avgLikesR20: 79834 avgCommentsR20: 7760 avgSelfCommentRatioR20: 0.02222222222222222 avgCommentLikeRatioR20: 0 avgCommentReplyRatioR20: 0.005555555555555556 avgViewsR20: 2215847 engageRateR20: 0.03953008681908395 - timestamp: 1755014400000 subscribers: 13800000 likes: 12895000 comments: 1058110 views: 11985928604 avgLength1Y: 611 avgLikes1Y: 80094 avgComments1Y: 6573 avgSelfCommentRatio1Y: 0.0214285714285714 avgCommentLikeRatio1Y: 0.0012422360248447205 avgCommentReplyRatio1Y: 0.002173913043478261 avgViews1Y: 2287655 engageRate1Y: 0.03788389841176463 avgLengthR20: 815.0555555555555 avgLikesR20: 75723 avgCommentsR20: 7257 avgSelfCommentRatioR20: 0.024999999999999998 avgCommentLikeRatioR20: 0 avgCommentReplyRatioR20: 0.005555555555555556 avgViewsR20: 2063091 engageRateR20: 0.04022061181340748 quotaUsed: 3 quotaUsedTotal: 6027 remainingPlanCredit: 993973 remainingPrepurchasedCredit: 0 timestamp: 1755503517606 error: '' success: true '403': description: Forbidden content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/BasicYoutubeAndHistoryResult' quotaUsed: type: number description: API credits that were used to make this call. quotaUsedTotal: type: number description: Total API credits used since the last billing cycle. remainingPlanCredit: type: number description: >- The number of remaining free API credits that come with your subscription plan. These API credits are renewed every billing cycle. remainingPrepurchasedCredit: type: number description: >- The number of remaining extra purchased API credits. These API credits do not expire until used. timestamp: type: number description: >- Unix timestamp of the call request that the server received. error: type: string description: Errors that occurred during the API call. success: type: boolean description: It is TRUE when the call is successful. examples: default: value: data: null quotaUsed: 0 quotaUsedTotal: 0 remainingPlanCredit: 0 remainingPrepurchasedCredit: 0 timestamp: 1755503514817 error: APIKeyOnlyForTesting success: false servers: - url: https://dev.creatordb.app/v2 description: CreatorDB API Endpoint - prod version x-codeSamples: - lang: bash label: cURL source: | curl --request GET \ --url 'https://dev.creatordb.app/v2/youtubeHistory?youtubeId=UCm-X6o81nRsXQTmqpyArkBQ' \ --header 'Accept: application/json' \ --header 'apiId: LE6DPZQkR3TQShxofXoD2j8qCBu1-f0jti665m1t50dwDD12W' components: schemas: BasicYoutubeAndHistoryResult: type: object additionalProperties: false properties: basicYoutube: $ref: '#/components/schemas/BasicYoutube' histories: type: array items: $ref: '#/components/schemas/YoutubeHistoryDay' required: - basicYoutube - histories BasicYoutube: type: object additionalProperties: false properties: youtubeId: type: string description: Unique ID of the YouTube channel. youtubeName: type: string description: The YouTube channel name. displayId: type: string description: The YouTube creator's handle. instagramId: type: string description: Instagram account ID of this YouTube creator. tiktokId: type: string description: >- The TikTok ID of the YouTube creator. Otherwise, this field is blank. avatar: type: string description: URL to the profile picture of the YouTube creator's account. hasEmail: type: boolean description: >- It is TRUE when the CreatorDB database has this YouTube creator's email contact. subscribers: type: number description: The current number of subscribers to this YouTube channel. views: type: number description: Total views of this YouTube channel. country: type: string description: The YouTube creator's country of origin. lang: type: string description: The YouTube creator's preferred language. createDate: type: number description: Unix timestamp of the date that the YouTube account was created. lastUploadTime: type: number description: Unix timestamp of the latest uploaded post by the YouTube creator. links: type: array items: type: object additionalProperties: false properties: title: type: string description: >- The name of a connected link from the About page of the YouTube channel. url: type: string description: URL of the link on the About page of the YouTube channel. required: - title - url hashtags: type: array description: Collection of hashtags that are included in all YouTube videos. items: type: string mainCategory: type: string description: >- The most common YouTube category selected by the creator from a list of default categories. topicIds: type: array description: >- Subcategories assigned to the default YouTube parent categories by CreatorDB's system. items: type: string nicheIds: type: array description: >- Niches assigned by CreatorDB's system to improve the content category keywords. items: type: string avgLength1Y: type: number description: >- Average video length in seconds for up to 800 YouTube videos uploaded in one year. avgLikes1Y: type: number description: >- Average likes per video for up to 800 YouTube videos uploaded in one year. avgComments1Y: type: number description: >- Average comments per video for up to 800 YouTube videos uploaded in one year. avgSelfCommentRatio1Y: type: number description: The YouTube creator's self-comment ratio per video in one year. avgCommentLikeRatio1Y: type: number description: Average comments to likes ratio per YouTube video in one year. avgCommentReplyRatio1Y: type: number description: Average comments to replies ratio per YouTube video in one year. avgViews1Y: type: number description: >- Average views per YouTube video for up to 800 videos uploaded in one year. engageRate1Y: type: number description: >- The average engagement rate for up to 800 YouTube videos uploaded in one year. The YouTube engagement rate is calculated by adding likes and comments and then dividing by views. avgLengthR20: type: number description: >- Average video length in seconds for the YouTube creator's most recent 20 YouTube videos uploaded. avgLikesR20: type: number description: >- Average likes per video for the YouTube creator's latest 20 uploaded videos. avgCommentsR20: type: number description: >- Average comments per video for this YouTube creator's latest 20 uploaded videos. avgSelfCommentRatioR20: type: number description: >- The YouTube creator's self-comment ratio per video among the most recent 20 comments. avgCommentLikeRatioR20: type: number description: >- The ratio of the creator's self-likes divided by the top 20 comments is averaged from the most recent 20 videos to find the creator's engagement rate. avgCommentReplyRatioR20: type: number description: >- Average comments to replies ratio for the latest 20 comments per YouTube video. avgViewsR20: type: number description: >- Average views per YouTube video for the latest 20 uploaded pieces of content. engageRateR20: type: number description: >- Average engagement rate of the YouTube creator's latest 20 uploaded pieces of content. gRateSubscribers: type: number description: The growth rate of the YouTube channel subscribers over 30 days. gRateViews: type: number description: >- The growth rate of the YouTube creator's total video views over 30 days. gRateAvgViewsR20: type: number description: >- The growth rate for average views of the YouTube creator's most recent 20 posts over 30 days. gRateEngageRateR20: type: number description: >- The growth rate for engagement rate of the YouTube creator's most recent 20 posts over 30 days. recentVideos: type: array items: $ref: '#/components/schemas/YoutubeVideoInfo' required: - youtubeId - youtubeName - displayId - instagramId - tiktokId - avatar - hasEmail - subscribers - views - country - lang - createDate - lastUploadTime - links - hashtags - mainCategory - topicIds - nicheIds - avgLength1Y - avgLikes1Y - avgComments1Y - avgSelfCommentRatio1Y - avgCommentLikeRatio1Y - avgCommentReplyRatio1Y - avgViews1Y - engageRate1Y - avgLengthR20 - avgLikesR20 - avgCommentsR20 - avgSelfCommentRatioR20 - avgCommentLikeRatioR20 - avgCommentReplyRatioR20 - avgViewsR20 - engageRateR20 - gRateSubscribers - gRateViews - gRateAvgViewsR20 - gRateEngageRateR20 - recentVideos YoutubeHistoryDay: type: object additionalProperties: false properties: timestamp: type: number description: Unix timestamp of when the YouTube data snapshot was collected. subscribers: type: number description: Total subscribers of this YouTube channel. likes: type: number description: Total likes of this YouTube channel. comments: type: number description: Total number of comments on a YouTube creator's channel. views: type: number description: Total views of this YouTube channel. avgLength1Y: type: number description: >- The average video length in seconds for up to 800 videos uploaded last year. avgLikes1Y: type: number description: The average likes per video for up to 800 videos uploaded last year. avgComments1Y: type: number description: >- The average comments per video for up to 800 videos uploaded last year. avgSelfCommentRatio1Y: type: number description: >- The ratio of the YouTube creator's self-comments per video to total comments on a specified date in one year. avgCommentLikeRatio1Y: type: number description: >- The ratio of average comments per video to likes on a specified date in one year. avgCommentReplyRatio1Y: type: number description: >- The ratio of average comments per video to replies on a specified date in one year. avgViews1Y: type: number description: >- The average number of views per video for up to 800 videos uploaded last year. engageRate1Y: type: number description: >- The average engagement rate for a YouTube video is based on up to 800 videos uploaded last year. avgLengthR20: type: number description: >- The average video length in seconds for the YouTube creator's recent 20 uploads. avgLikesR20: type: number description: >- The average likes per video for the YouTube creator's recent 20 uploads. avgCommentsR20: type: number description: >- The average comments per video for the YouTube creator's recent 20 uploads. avgSelfCommentRatioR20: type: number description: >- The ratio of the YouTube creator's self-comments per video to the top 20 comments on a specified date in one year. avgCommentLikeRatioR20: type: number description: >- The ratio of average top 20 comments per video to likes for a specified date in one year. avgCommentReplyRatioR20: type: number description: >- The ratio of average top 20 comments per video to replies for a specific date in one year. avgViewsR20: type: number description: >- The average number of views per video for the YouTube creator's recent 20 uploads. engageRateR20: type: number description: >- The average engagement rate for a video is based on the YouTube creator's recent 20 videos. required: - timestamp - subscribers - likes - comments - views - avgLength1Y - avgLikes1Y - avgComments1Y - avgSelfCommentRatio1Y - avgCommentLikeRatio1Y - avgCommentReplyRatio1Y - avgViews1Y - engageRate1Y - avgLengthR20 - avgLikesR20 - avgCommentsR20 - avgSelfCommentRatioR20 - avgCommentLikeRatioR20 - avgCommentReplyRatioR20 - avgViewsR20 - engageRateR20 YoutubeVideoInfo: type: object additionalProperties: false properties: uploadDate: type: number description: Unix timestamp of the YouTube video upload time. videoId: type: string description: Unique ID of the video that is auto-generated. length: type: number description: Length of the YouTube video in seconds. title: type: string description: The title of the YouTube video. likes: type: number description: The number of likes the YouTube video received. comments: type: number description: The number of comments on this YouTube video. selfCommentRatio: type: number description: >- The ratio of the YouTube creator's self-comments to recent 20 comments. commentLikeRatio: type: number description: The ratio of comments to likes for this YouTube video. commentReplyRatio: type: number description: The ratio of comments to the YouTube creator replies for this video. views: type: number description: The number of views for the YouTube video. engageRate: type: number description: >- The engagement rate of this YouTube video. The engagement rate is calculated by adding the likes and comments and then dividing by the number of video views. category: type: string description: >- The video category assigned by the YouTube creator from a default category list. lang: type: string description: Language of the YouTube video. isPaidPromote: type: boolean description: >- It is TRUE when the YouTube creator flags the video as containing an advertisement. isStreaming: type: boolean description: It is TRUE when the YouTube video is a live stream. isShorts: type: boolean description: It is TRUE when the video is a YouTube short. hashtags: type: array description: Hashtags that are included in this YouTube video. items: type: string required: - uploadDate - videoId - length - title - likes - comments - selfCommentRatio - commentLikeRatio - commentReplyRatio - views - engageRate - category - lang - isPaidPromote - isStreaming - isShorts - hashtags ````