YouTube creator insights

  • The creator insights feature, currently in beta and available only to developers on an allowlist, helps agencies and advertisers find relevant YouTube creators.

  • The API offers four main functions: Creator Discoverability, Creator Brand Insights, Creator Insights, and Trending Insights.

  • To use the API, partners must meet eligibility requirements including having a planning tool, using the API for advertising opportunities, completing an assessment, following data usage requirements, and signing agreements.

  • You can generate creator insights by sending a request to the ContentCreatorInsightsService.GenerateCreatorInsights method with inputs based on whether you need creator discoverability, creator brand insights, or specific channel insights.

  • Trending insights can be generated using the ContentCreatorInsightsService.GenerateTrendingInsights method by providing audience attributes or content topics for a specific country.

Discover and fetch insights about YouTube creators with the creator insights feature in ContentCreatorInsightsService. This service helps agencies and advertisers find creators who are relevant to their target audience.

The API has four main functions:

  1. Creator discoverability: Find relevant creators for a given set of topics, demographics, audiences, or creator attributes.
  2. Creator topic insights: Fetch insights about relevant creators who make content about specified topics.
  3. Creator insights: Fetch insights about specific YouTube channels, such as their subscriber count, view count, and audience demographics.
  4. Trending insights: Fetch insights about specific trends, based on specific audiences or topics.

Local creator discovery (finding creators who are based in or post from a given country and are viewed in that country) is supported when using topic-based creator discovery or trending insights by requesting supplemental data. You can also request brand sentiment insights for topic-based trending insights by requesting supplemental data.

Eligibility requirements

GenerateCreatorInsights is a private component of the Google Ads API offered with a non-exclusive, royalty-free data license. Signed partners can use the standard Google Ads client libraries to explore YouTube creators and content. To be eligible, partners must satisfy the following conditions:

  • Have a planning tool or user interface that integrates the Google Ads API.
  • Use the API to explore YouTube content and creators for potential advertising opportunities.
  • Complete a pre-screen assessment to verify eligibility.
  • Follow data usage requirements and undergo periodic data audits.
  • Accept the Google Ads API terms of service and the associated data usage policy.

Contact your Google representative for more information.

Generate creator insights

To generate creator insights, send a request to the GenerateCreatorInsights method. This method has a limit of 5 queries per second (QPS). It accepts different criteria depending on whether you want creator discoverability, topic-based creator search, or channel-specific creator insights. You must provide the target country locations in country_locations.

  1. Creator discoverability (search_attributes): Provide a list of audience attributes—such as age, gender, and user interests (affinity, in-market, and life event audiences)—using the search_attributes field to find creators whose audiences match those attributes. You can also provide creator attributes to filter for creators whose content matches specific attributes.

    Retrieve available audience attributes using ListAudienceInsightsAttributes by specifying the dimensions you need, such as KNOWLEDGE_GRAPH for topics of interest. To combine attributes using boolean AND and OR groups, use audience_combinations as described in Complex audience combinations.

  2. Creator topic insights (search_topics): Provide a list of content topics using the search_topics field. The API returns relevant creators who make content about the specified topics. Data is fetched for the country specified in country_locations (this option supports a single country per request).

    Supported entities in search_topics must be tagged with either the CONTENT_TRENDING_INSIGHTS or CREATOR_TOPIC_INSIGHTS capability. Use ListAudienceInsightsAttributes to retrieve supported entity capabilities.

  3. Creator insights (search_channels): Provide a list of YouTube channel IDs, YouTube channel handles (youtube_channel_handles, available in v25 and later), or a combination of both using the search_channels field. The API returns insights about those specific channels.

Complex audience combinations

In both GenerateCreatorInsights and GenerateTrendingInsights, you can define complex audience attribute relationships using audience_combinations. This field lets you combine audience attributes with boolean logic (AND and OR) beyond the flat union (OR) behavior of audience_attributes:

  • Each InsightsAudienceAttributeGroup within audience_combinations combines its attributes with a logical OR.
  • Multiple InsightsAudienceAttributeGroup items in audience_combinations are combined with a logical AND.

For example, to target an audience interested in ("Skin care" OR "Hair care") AND "Cosmetics", include two InsightsAudienceAttributeGroup items in audience_combinations:

  1. Group 1 containing the Knowledge Graph entity attributes for "Skin care" and "Hair care".
  2. Group 2 containing the Knowledge Graph entity attribute for "Cosmetics" (such as /m/014trl).

Supplemental data and local creators

By default, only core insight data is returned. You can request optional features and additional data in your response by setting the repeated field supplemental_data.

For example, you can request local creator data by adding the LOCAL_CREATOR_DATA enum value to supplemental_data. If you search for creators using search_topics (and the topic is a Knowledge Graph entity tagged with the CREATOR_TOPIC_INSIGHTS capability), the API populates the local_creator_insights field in the response with local creators who have consented to share their location data.

Keep the following specifications in mind for local creator discovery:

  • Definition: Local creators are creators who are based in or post from the selected country and are viewed in that country.
  • Constraint: Local creator discovery is not supported when sub_country_locations is set in the request.
  • Capabilities: You can retrieve the list of supported Knowledge Graph entities and their capabilities using ListAudienceInsightsAttributes.

The GenerateCreatorInsights method returns a GenerateCreatorInsightsResponse object containing the following fields:

  • creator_insights: A list of YouTubeCreatorInsights objects matching your core criteria.
  • local_creator_insights: A list of YouTubeCreatorInsights objects for local creators. This is only populated if LOCAL_CREATOR_DATA was requested and the criteria used was search_topics.

Each YouTubeCreatorInsights object contains:

  • creator_name: The name of the creator.
  • creator_channels: A list of YouTubeChannelInsights objects. Channel details and channel_metrics (YouTubeMetrics) are returned inside each YouTubeChannelInsights object in creator_channels.

The YouTubeMetrics object contains:

  • Subscriber, view, and video counts
  • Total like, share, and comment counts across all of the channel's videos
  • Lifetime engagement rate (total engagement divided by total views)
  • Average views, likes, shares, and comments per video over the last 28 days
  • Shorts view and video counts
  • Whether the creator is an active Shorts creator or an active livestream creator (has published one in the last 90 days)
  • Partnership opportunities

Engagement rate and average views, likes, and comments per video are non-public metrics that are populated only when the creator has consented to share them.

To check if a creator is eligible for original branded content partnerships, inspect partnership_opportunities; a creator is eligible if the list contains CREATOR_PARTNERSHIPS.

The YouTubeChannelInsights object contains the following information about a YouTube channel:

  • Channel name, ID, handle, URL, description, and thumbnail URL
  • Channel creation date and associated country
  • Channel metrics
  • Channel audience attributes (such as age, gender, and user interest breakdown)
  • Channel attributes (the attributes associated with the channel's content)
  • Top videos
  • Channel type and content languages
  • Relevance score (for topic trend searches only)
  • Whether the creator has given consent to share non-public metrics

GenerateCreatorInsights request and response reference

Call GenerateCreatorInsights on ContentCreatorInsightsService at the following endpoint:

POST https://googleads.googleapis.com/v26/customers/{customer_id}:generateCreatorInsights

The following table summarizes the fields on GenerateCreatorInsightsRequest:

Field path Requirement Format and constraints
customer_id Required 10-digit customer ID (string) without hyphens.
customer_insights_group Required User-defined name (string) of the customer or brand being planned for.
country_locations[] Required List of country LocationInfo objects (geo_target_constant, such as "geoTargetConstants/2840"). Must contain a single country when search_topics is used.
sub_country_locations[] Optional Sub-country LocationInfo filters; supported only with search_attributes and incompatible with LOCAL_CREATOR_DATA.
search_attributes criteria (oneof) SearchAttributes containing:
• audience_attributes[]: age_range, gender, device, parental_status, income_range (plus user_interest, entity, or category when audience_combinations is unused).
• audience_combinations[]: AND-of-ORs InsightsAudienceAttributeGroup items.
• creator_attributes[]: Knowledge Graph entity items with the CREATOR_ATTRIBUTE capability.
search_topics criteria (oneof) SearchTopics containing entities[] (AudienceInsightsEntity with knowledge_graph_machine_id tagged with CREATOR_TOPIC_INSIGHTS or CONTENT_TRENDING_INSIGHTS).
search_channels criteria (oneof) YouTubeChannels containing youtube_channels[] (channel_id) and/or youtube_channel_handles[] (handles starting with @, such as "@youtubecreators").
supplemental_data[] Optional ContentCreatorInsightsSupplementalData values. Set LOCAL_CREATOR_DATA on a single-country search_topics request (for entities with CREATOR_TOPIC_INSIGHTS) to populate local_creator_insights[].
insights_application_info Optional AdditionalApplicationInfo metadata about the application issuing the request.

The GenerateCreatorInsightsResponse message returns the following fields:

Response field Type Description
creator_insights[] YouTubeCreatorInsights Creators matching your core criteria (creator_name and creator_channels[]).
local_creator_insights[] YouTubeCreatorInsights Local creators who consented to share location data (populated when LOCAL_CREATOR_DATA is requested with search_topics on an entity with CREATOR_TOPIC_INSIGHTS).
creator_channels[] YouTubeChannelInsights Metadata: display_name, youtube_channel.channel_id, handle, channel_url, publish_date, country_location, and data_sharing_consent_given.
Insights & content: channel_audience_attributes[] (consent-gated), channel_attributes[], top_videos[], language_distributions[], relevance_score (populated only for GenerateTrendingInsights with search_topics), and channel_metrics.
channel_metrics YouTubeMetrics Public metrics: subscriber_count, views_count, video_count, likes_count, shares_count, comments_count, shorts_views_count, shorts_video_count, is_active_shorts_creator, is_active_live_stream_creator, and partnership_opportunities[].
Consent-gated metrics: engagement_rate and 28-day per-video averages (average_views_per_video, average_likes_per_video, average_shares_per_video, average_comments_per_video).

GenerateCreatorInsights REST request and response examples

The following example discovers creators using searchAttributes with demographic audienceAttributes, boolean audienceCombinations ("Skin care" OR "Hair care", AND "Cosmetics"), and creatorAttributes:

POST https://googleads.googleapis.com/v26/customers/{customer_id}:generateCreatorInsights

{
  "customerInsightsGroup": "Spring Skincare Campaign",
  "countryLocations": [
    {
      "geoTargetConstant": "geoTargetConstants/2840"
    }
  ],
  "searchAttributes": {
    "audienceAttributes": [
      {
        "ageRange": {
          "type": "AGE_RANGE_25_34"
        }
      },
      {
        "gender": {
          "type": "FEMALE"
        }
      }
    ],
    "audienceCombinations": [
      {
        "attributes": [
          {
            "entity": {
              "knowledgeGraphMachineId": "/m/015c4z"
            }
          },
          {
            "entity": {
              "knowledgeGraphMachineId": "/m/018bb_"
            }
          }
        ]
      },
      {
        "attributes": [
          {
            "entity": {
              "knowledgeGraphMachineId": "/m/014trl"
            }
          }
        ]
      }
    ],
    "creatorAttributes": [
      {
        "entity": {
          "knowledgeGraphMachineId": "/m/014trl"
        }
      }
    ]
  }
}

To fetch topic-based creators along with local creators, use searchTopics and include "LOCAL_CREATOR_DATA" in supplementalData:

POST https://googleads.googleapis.com/v26/customers/{customer_id}:generateCreatorInsights

{
  "customerInsightsGroup": "Spring Skincare Campaign",
  "countryLocations": [
    {
      "geoTargetConstant": "geoTargetConstants/2840"
    }
  ],
  "supplementalData": [
    "LOCAL_CREATOR_DATA"
  ],
  "searchTopics": {
    "entities": [
      {
        "knowledgeGraphMachineId": "/m/014trl"
      }
    ]
  }
}

To fetch insights for specific YouTube channels by channel ID or handle, use searchChannels:

POST https://googleads.googleapis.com/v26/customers/{customer_id}:generateCreatorInsights

{
  "customerInsightsGroup": "Spring Skincare Campaign",
  "countryLocations": [
    {
      "geoTargetConstant": "geoTargetConstants/2840"
    }
  ],
  "searchChannels": {
    "youtubeChannels": [
      {
        "channelId": "UCxxxxxxxxxxxxxxxxxxxxxx"
      }
    ],
    "youtubeChannelHandles": [
      "@exampleskincare"
    ]
  }
}

A successful GenerateCreatorInsightsResponse returns creatorInsights[] (and localCreatorInsights[] when LOCAL_CREATOR_DATA is requested):

{
  "creatorInsights": [
    {
      "creatorName": "Example Skincare Creator",
      "creatorChannels": [
        {
          "displayName": "Example Skincare Channel",
          "youtubeChannel": {
            "channelId": "UCxxxxxxxxxxxxxxxxxxxxxx"
          },
          "channelUrl": "https://www.youtube.com/channel/UCxxxxxxxxxxxxxxxxxxxxxx",
          "handle": "@exampleskincare",
          "publishDate": "2020-03-15",
          "countryLocation": {
            "geoTargetConstant": "geoTargetConstants/2840"
          },
          "dataSharingConsentGiven": true,
          "channelMetrics": {
            "subscriberCount": "450000",
            "viewsCount": "38200000",
            "videoCount": "210",
            "likesCount": "1950000",
            "commentsCount": "84000",
            "engagementRate": 0.056,
            "averageViewsPerVideo": 62000.0,
            "shortsViewsCount": "14500000",
            "shortsVideoCount": "95",
            "isActiveShortsCreator": true,
            "isActiveLiveStreamCreator": false,
            "partnershipOpportunities": [
              "CREATOR_PARTNERSHIPS",
              "PARTNERSHIP_ADS"
            ]
          }
        }
      ]
    }
  ],
  "localCreatorInsights": []
}

To generate trending insights, send a request to the GenerateTrendingInsights method. This method has a limit of 5 queries per second (QPS). It accepts two types of input depending on whether you want audience trends or topic trends, and requires a target country location.

  1. Audience trends (search_audience): Provide a list of audience attributes (such as age, gender, and user interests) in the audience_attributes field of search_audience and, optionally, use audience_combinations to combine attributes with boolean AND/OR logic. The API returns a list of trending insights for those audiences, including metrics such as the percentage change in the trend's value over the comparison period.

    Developers with access to ContentCreatorInsightsService have automatic access to ListAudienceInsightsAttributes in AudienceInsightsService (see the Audience insights guide). Other endpoints in AudienceInsightsService require a separate allowlist.

  2. Topic trends (search_topics): Provide a list of content topics in the search_topics field. The API returns trending insights for those topics, including the percentage change in the trend's value over the comparison period. You can also request local creators or brand sentiment insights by setting supplemental_data.

    KNOWLEDGE_GRAPH attributes returned by ListAudienceInsightsAttributes include one or more InsightsKnowledgeGraphEntityCapabilities tags; entities tagged CONTENT_TRENDING_INSIGHTS are supported as topics in GenerateTrendingInsights.

Similar to generating creator insights, you can request optional features in trending insights by setting the repeated field supplemental_data to LOCAL_CREATOR_DATA or BRAND_SENTIMENT_DATA:

  • Local creators (LOCAL_CREATOR_DATA): When your trending request uses search_topics (and the topic is a Knowledge Graph entity tagged with the CREATOR_TOPIC_INSIGHTS capability), setting supplemental_data to LOCAL_CREATOR_DATA populates the related_local_creators field on the returned TrendInsight objects with related local creators who have consented to share their location data. Local creator discovery is incompatible with sub_country_locations.
  • Brand sentiment (BRAND_SENTIMENT_DATA): When your trending request uses search_topics and the requested Knowledge Graph entity topic has the BRAND capability, setting supplemental_data to BRAND_SENTIMENT_DATA populates the brand_sentiment_insights field on the returned TrendInsight objects.

Measuring brand sentiment uses Gemini AI models to analyze YouTube video content related to the brand, categorizing the sentiment as positive, negative, or neutral. Only the video content itself is analyzed; user comments are not included.

The GenerateTrendingInsights method returns a list of TrendInsight objects, each containing:

  • trend_attribute: The primary AudienceInsightsAttributeMetadata for the trend.
  • trend_metrics: The metrics for the trend, such as percentage change over the comparison period.
  • trend: An InsightsTrend value (EMERGING, RISING, SUSTAINED, or DECLINING) indicating the direction of the trend. See trend_metrics.trend_change_percent for the size of the change.
  • trend_data_points: Historical data points for the trend. Only populated for trends using search_topics.
  • related_videos: A list of AudienceInsightsAttributeMetadata objects for trending videos associated with the trend's topic (only populated for trends using search_topics). For these attributes, the nested YouTubeVideoAttributeMetadata is populated with video-level metadata (URL, thumbnail URL, view and like counts) and channel-level metadata (channel ID, name, and URL).
  • related_creators: A list of YouTubeCreatorInsights objects for creators related to the trend's topic (only populated for trends using search_topics).
  • related_local_creators: A list of YouTubeCreatorInsights objects for local creators related to the trend's topic who have consented to share their location data. Only populated when LOCAL_CREATOR_DATA is requested (see Supplemental data, local creators, and brand sentiment).
  • brand_sentiment_insights: A list of BrandSentimentInsight objects for the trend (populated when the request uses search_topics for an entity with the BRAND capability and requests BRAND_SENTIMENT_DATA). Each BrandSentimentInsight object contains:
    • month: The month that the brand sentiment represents in YYYY-MM format.
    • has_insufficient_data: Whether there is insufficient data to calculate the brand sentiment.
    • sentiment_distributions: Distribution of sentiment between positive, negative, and neutral, calculated as the proportion of views for videos corresponding to the brand with each sentiment.
    • sentiment_summaries: AI-generated summaries of positive and negative themes in content related to the brand, along with sample videos for each sentiment. Summaries are generated only for positive and negative sentiment, not neutral.

Call GenerateTrendingInsights on ContentCreatorInsightsService at the following endpoint:

POST https://googleads.googleapis.com/v26/customers/{customer_id}:generateTrendingInsights

The following table summarizes the fields on GenerateTrendingInsightsRequest:

Field path Requirement Format and constraints
customer_id Required 10-digit customer ID (string) without hyphens.
customer_insights_group Required User-defined name (string) of the customer or brand being planned for.
country_location Required Single country LocationInfo (geo_target_constant, such as "geoTargetConstants/2840").
sub_country_locations[] Optional Sub-country LocationInfo filters; supported only for search_audience and incompatible with LOCAL_CREATOR_DATA.
search_audience criteria (oneof) SearchAudience containing:
• audience_attributes[] (required): age_range, gender, parental_status, income_range (plus user_interest, entity, or category when audience_combinations is unused).
• audience_combinations[] (optional): AND-of-ORs attribute groups.
search_topics criteria (oneof) SearchTopics containing entities[] (AudienceInsightsEntity with knowledge_graph_machine_id tagged with CONTENT_TRENDING_INSIGHTS).
supplemental_data[] Optional ContentCreatorInsightsSupplementalData values:
• LOCAL_CREATOR_DATA: Populates related_local_creators[] for search_topics entities with CREATOR_TOPIC_INSIGHTS.
• BRAND_SENTIMENT_DATA: Populates brand_sentiment_insights[] for search_topics entities with BRAND.
insights_application_info Optional AdditionalApplicationInfo metadata about the application issuing the request.

The GenerateTrendingInsightsResponse message returns TrendInsight entries in trend_insights[]:

TrendInsight field Type Description
trend_attribute AudienceInsightsAttributeMetadata Primary attribute for the trend (dimension, display_name, attribute).
trend_metrics TrendInsightMetrics Metrics over the 3-month comparison period (views_count and views_indexed_value for search_topics; audience_share for search_audience; trend_change_percent).
trend InsightsTrend Direction of the trend (EMERGING, RISING, SUSTAINED, or DECLINING).
trend_data_points[] TrendInsightDataPoint Monthly historical data (month in YYYY-MM format and trend_metrics); populated for search_topics.
related_videos[] AudienceInsightsAttributeMetadata Trending videos with YouTubeVideoAttributeMetadata; populated for search_topics.
related_creators[] YouTubeCreatorInsights Creators related to the topic; populated for search_topics.
related_local_creators[] YouTubeCreatorInsights Consenting local creators; populated for search_topics when LOCAL_CREATOR_DATA is requested on an entity with CREATOR_TOPIC_INSIGHTS.
brand_sentiment_insights[] BrandSentimentInsight Monthly brand sentiment (month, has_insufficient_data, sentiment_distributions[], sentiment_summaries[]); populated for search_topics when BRAND_SENTIMENT_DATA is requested on an entity with the BRAND capability.

The following example calls GenerateTrendingInsights using searchTopics for a Knowledge Graph brand entity (/g/11example_brand, tagged with CONTENT_TRENDING_INSIGHTS, CREATOR_TOPIC_INSIGHTS, and BRAND) and requests both LOCAL_CREATOR_DATA and BRAND_SENTIMENT_DATA:

POST https://googleads.googleapis.com/v26/customers/{customer_id}:generateTrendingInsights

{
  "customerInsightsGroup": "Spring Skincare Campaign",
  "countryLocation": {
    "geoTargetConstant": "geoTargetConstants/2840"
  },
  "supplementalData": [
    "LOCAL_CREATOR_DATA",
    "BRAND_SENTIMENT_DATA"
  ],
  "searchTopics": {
    "entities": [
      {
        "knowledgeGraphMachineId": "/g/11example_brand"
      }
    ]
  }
}

A successful GenerateTrendingInsightsResponse returns TrendInsight entries in trendInsights[]:

{
  "trendInsights": [
    {
      "trendAttribute": {
        "dimension": "KNOWLEDGE_GRAPH",
        "displayName": "Example Skincare Brand",
        "attribute": {
          "entity": {
            "knowledgeGraphMachineId": "/g/11example_brand"
          }
        }
      },
      "trendMetrics": {
        "viewsCount": "18500000",
        "viewsIndexedValue": "82",
        "trendChangePercent": 0.24
      },
      "trend": "RISING",
      "trendDataPoints": [
        {
          "month": "2026-05",
          "trendMetrics": {
            "viewsCount": "18500000",
            "viewsIndexedValue": "82",
            "trendChangePercent": 0.08
          }
        }
      ],
      "brandSentimentInsights": [
        {
          "month": "2026-05",
          "hasInsufficientData": false,
          "sentimentDistributions": [
            {
              "sentiment": "SENTIMENT_POSITIVE",
              "sentimentShare": 0.68
            },
            {
              "sentiment": "SENTIMENT_NEUTRAL",
              "sentimentShare": 0.25
            },
            {
              "sentiment": "SENTIMENT_NEGATIVE",
              "sentimentShare": 0.07
            }
          ]
        }
      ],
      "relatedVideos": [],
      "relatedCreators": [],
      "relatedLocalCreators": []
    }
  ]
}
Previous
Audience insights
Next
YouTube benchmarks