> ## 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 a topic report > Get a detailed YouTube topic report. The report data includes the number of channels in this topic, various metrics within one year period, and demographic data. Currently, this API call only supports YouTube channels. ## OpenAPI ````yaml /api-v2/api-v2.yaml get /topicReport 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: /topicReport: get: tags: - Topic summary: Get a topic report description: >- Get a detailed YouTube topic report. The report data includes the number of channels in this topic, various metrics within one year period, and demographic data. Currently, this API call only supports YouTube channels. operationId: getTopicReport parameters: - name: apiId in: header description: '' required: true schema: type: string examples: - LE6DPZQkR3TQShxofXoD2j8qCBu1-f0jti665m1t50dwDD12W - name: topicId in: query description: '' required: true schema: type: string examples: - id_minecraft_Gaming responses: '200': description: OK content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/DetailTopicReport' 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: ytDgMainCountry: USA ytDgMainCountryRatio: 0.25619661399548493 ytDgCountryBreakdown: - country: USA value: 0.25619661399548493 - country: DEU value: 0.07613182844243792 - country: FRA value: 0.05287494356659145 ytDgGenderMaleRatio: 0.6669777319587632 ytDgGenderFemaleRatio: 0.3327748453608248 ytDgAvgAge: 31.89085082474229 ytDgAgeBreakdown: - 0.06435340206185572 - 0.3039703092783508 - 0.24169670103092772 topicId: id_minecraft_Gaming topicName: Minecraft channelNumber: 800 avgViews1Y: 308043 engageRate1Y: 0.05511483035821551 avgLikes1Y: 8782 avgDislikes1Y: 4 avgComments1Y: 602 avgRating1Y: 0.15336445215445188 avgLength1Y: 1715 avgViewsR20: 260339 engageRateR20: 0.058044981782167174 avgLikesR20: 8091 avgDislikesR20: 0 avgCommentsR20: 582 avgRatingR20: 0 avgLengthR20: 1594 countryBreakdown: - country: USA count: 291 - country: GBR count: 92 - country: ESP count: 89 relatedTopicBreakdown: - topicId: id_minecraft_Gaming count: 800 - topicId: id_casualgaming_Gaming count: 765 - topicId: id_sandbox_Gaming count: 748 relatedNicheBreakdown: - nicheId: id_minecraft_Gaming count: 476 - nicheId: id_funny_Gaming count: 133 - nicheId: id_roblox_Gaming count: 129 rankInAllTopics: rankSubs: 89.1213389121339 rankViews: 83.89121338912133 rankAvgViews: 91.63179916317992 rankEngage: 92.25941422594143 rankGrowthInAllTopics: rankSubs: 17.991631799163173 rankViews: 36.82008368200837 rankAvgViews: 76.98744769874477 rankEngage: 51.04602510460251 rankByCategories: rankSubs: 82.8125 rankViews: 82.8125 rankAvgViews: 93.75 rankEngage: 92.1875 rankGrowthByCategories: rankSubs: 43.75 rankViews: 53.125 rankAvgViews: 87.5 rankEngage: 34.375 gSubscribers: 0.0029053182638998356 gTotalViews: 0.005916388772396742 gAvgViewsR20: 0.011351231659136731 gEngageRateR20: -0.001941457284146474 quotaUsed: 25 quotaUsedTotal: 6049 remainingPlanCredit: 993951 remainingPrepurchasedCredit: 0 timestamp: 1755503514906 error: '' success: true '403': description: Forbidden content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/DetailTopicReport' 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: 1755503514055 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/topicReport?topicId=id_minecraft_Gaming' \ --header 'Accept: application/json' \ --header 'apiId: LE6DPZQkR3TQShxofXoD2j8qCBu1-f0jti665m1t50dwDD12W' components: schemas: DetailTopicReport: type: object additionalProperties: false properties: ytDgMainCountry: type: string description: The country where the largest share of viewers is located ytDgMainCountryRatio: type: number description: The ratio of viewers in the country with the largest share ytDgCountryBreakdown: type: array description: Country breakdown of viewers items: type: object additionalProperties: false properties: country: type: string description: Countries where viewers are located. value: type: number description: The number of viewers from the country. required: - country - value ytDgGenderMaleRatio: type: number description: The ratio of male viewers ytDgGenderFemaleRatio: type: number description: The ratio of female viewers ytDgAvgAge: type: number description: The average viewer age ytDgAgeBreakdown: type: array description: >- The number of viewers in each age group: [13–17], [18–24], [25–34], [35–44], [45–54], [55–64], [65+] items: type: number topicId: type: string description: Name of the topic ID. topicName: type: string description: Name of the topic. channelNumber: type: number description: Total channels labeled with this topic. avgViews1Y: type: number description: >- Average views for all YouTube channels with related topic content in one year. engageRate1Y: type: number description: >- The average engagement rate of a video is based on up to 800 videos on this topic uploaded from the last year. avgLikes1Y: type: number description: >- Average likes for all YouTube channels with related topic content in one year. avgDislikes1Y: type: number description: Deprecated. avgComments1Y: type: number description: >- Average comments for all YouTube channels with related topic content in one year. avgRating1Y: type: number description: Average ratings for all YouTube channels with related topic content. avgLength1Y: type: number description: >- Average video length of all YouTube channels with related topic content in one year. avgViewsR20: type: number description: >- Average views for the most recent 20 videos for all YouTube channels with related topic content. engageRateR20: type: number description: >- The average engagement rate of a video is based on up to 800 videos on this topic uploaded from the last year. avgLikesR20: type: number description: >- Average likes for the most recent 20 videos for all YouTube channels with related topic content. avgDislikesR20: type: number description: Deprecated. avgCommentsR20: type: number description: >- Average comments for the most recent 20 videos from all YouTube channels with related topic content. avgRatingR20: type: number description: >- Average ratings for the most recent 20 videos for all YouTube channels with related topic content. avgLengthR20: type: number description: >- Average video length for the most recent 20 videos for all YouTube channels with related topic content. countryBreakdown: type: array description: Break down of the country of origin for all YouTube creators. items: type: object additionalProperties: false properties: country: type: string description: >- Country of origin of YouTube creator channels labeled with this topic. count: type: number description: The ratio of YouTube creators from this country. required: - country - count relatedTopicBreakdown: type: array description: Other related topics. items: type: object additionalProperties: false properties: topicId: type: string description: Name of the topic ID. count: type: number description: The number of YouTube channels labeled in this topic. required: - topicId - count relatedNicheBreakdown: type: array description: Niches related to this topic. items: type: object additionalProperties: false properties: nicheId: type: string description: Name of the niche. count: type: number description: The number of YouTube channels labeled in this niche. required: - nicheId - count rankInAllTopics: $ref: '#/components/schemas/TopicRanks' description: >- Percentile ranking in all topics. These topics are defined by CreatorDB and act as a type of subcategory. rankGrowthInAllTopics: $ref: '#/components/schemas/TopicRanks' description: >- Percentile ranking of the growth rate by YouTube topics over 30 days. These topics are defined by CreatorDB and act as a type of subcategory. rankByCategories: $ref: '#/components/schemas/TopicRanks' description: Topic report ranking by YouTube categories. rankGrowthByCategories: $ref: '#/components/schemas/TopicRanks' description: >- Percentile ranking of the growth rate by YouTube categories over 30 days. gSubscribers: type: number description: The growth rate of subscribers for this topic over 30 days. gTotalViews: type: number description: The growth rate of total views for this topic over 30 days. gAvgViewsR20: type: number description: >- The growth rate of the average views for the most recent 20 videos on this topic over 30 days. gEngageRateR20: type: number description: >- The growth rate of the engagement rate from the most recent 20 videos on this topic over 30 days. required: - ytDgMainCountry - ytDgMainCountryRatio - ytDgCountryBreakdown - ytDgGenderMaleRatio - ytDgGenderFemaleRatio - ytDgAvgAge - ytDgAgeBreakdown - topicId - topicName - channelNumber - avgViews1Y - engageRate1Y - avgLikes1Y - avgDislikes1Y - avgComments1Y - avgRating1Y - avgLength1Y - avgViewsR20 - engageRateR20 - avgLikesR20 - avgDislikesR20 - avgCommentsR20 - avgRatingR20 - avgLengthR20 - countryBreakdown - relatedTopicBreakdown - relatedNicheBreakdown - rankInAllTopics - rankGrowthInAllTopics - rankByCategories - rankGrowthByCategories - gSubscribers - gTotalViews - gAvgViewsR20 - gEngageRateR20 TopicRanks: type: object additionalProperties: false properties: rankSubs: type: number description: >- The percentile ranking of subscribers for this YouTube topic label compared to all other topics. rankViews: type: number description: >- The percentile ranking of total views for this YouTube topic label compared to all other topics. rankAvgViews: type: number description: >- The percentile ranking of the average views for this YouTube topic label compared to all other topics. rankEngage: type: number description: >- The percentile ranking of the engagement rate for this YouTube topic label compared to all other topics. required: - rankSubs - rankViews - rankAvgViews - rankEngage ````