> [!IMPORTANT]
> **Important:** This feature is only available to accounts on an allowlist. Contact your Google representative if you need access to this feature.

All requests to [`AudienceInsightsService`](https://developers.google.com/google-ads/api/reference/rpc/v26/AudienceInsightsService) are rate-limited. Fewer requests
are permitted per day for [`generateAudienceCompositionInsights`](https://developers.google.com/google-ads/api/reference/rpc/v26/AudienceInsightsService/GenerateAudienceCompositionInsights) and
[`generateSuggestedTargetingInsights`](https://developers.google.com/google-ads/api/reference/rpc/v26/AudienceInsightsService/GenerateSuggestedTargetingInsights) than for other Audience Insights
methods. See [API quotas](https://developers.google.com/google-ads/api/docs/best-practices/quotas) for more details.

[`AudienceInsightsService`](https://developers.google.com/google-ads/api/reference/rpc/v26/AudienceInsightsService) lets you integrate Google audience insights data
into your planning tools. The data helps media agencies and media planners gain
a deeper understanding of their target audience, including demographics,
interests, and online behavior.

Audience insights help you understand an audience, category, topic, or brand by
providing a high-level overview. By analyzing user behaviors on related topics,
you can use these audience insights to uncover the associations and perceptions
that consumers have and identify new audience segments.

The API supports three primary use cases:

- **Refine and uncover audiences:** Understand consumers' unique interests and behaviors to identify new audiences for a brand, develop audience personas, and refine audience segmentation strategies.
- **Inform campaign planning:** Translate data outputs into YouTube target audiences to plan against, estimate the potential reach of targeted audiences, and measure the overlap between audience segments to maximize campaign reach.
- **Develop creative messages:** Tailor creative messages to your target audience based on the topics and affinities they engage with most.

## Eligibility requirements

To be eligible for [`AudienceInsightsService`](https://developers.google.com/google-ads/api/reference/rpc/v26/AudienceInsightsService), partners must satisfy the
following conditions:

- Have existing access, or eligibility for access, to [Insights Finder](https://ads.google.com/intl/en_us/home/tools/insights-finder/).
- Have a planning tool or user interface that integrates the API.
- Use the API for media planning purposes or other relevant use cases.
- Complete a pre-screen assessment.
- Follow data usage requirements and undergo periodic data audits.
- Accept the Google Ads API [terms of service](https://developers.google.com/google-ads/api/docs/api-policy/terms) and the associated data usage policy.

Contact your Google representative for more information.

## List insights eligible dates

A typical workflow begins by checking which calendar months and date windows are
available for analysis. The [`listInsightsEligibleDates`](https://developers.google.com/google-ads/api/reference/rpc/v26/AudienceInsightsService/ListInsightsEligibleDates) method returns a
[`ListInsightsEligibleDatesResponse`](https://developers.google.com/google-ads/api/reference/rpc/v26/ListInsightsEligibleDatesResponse), whose `data_months` field lists the
months (in `YYYY-MM` format) for which audience insights data is available.

The response's `last_thirty_days` field contains the exact date range that
[`generateAudienceCompositionInsights`](https://developers.google.com/google-ads/api/reference/rpc/v26/AudienceInsightsService/GenerateAudienceCompositionInsights) uses when `data_month` is not set
in the request.

## List audience insights attributes

Before querying audience composition or overlap metrics, discover valid
attribute IDs using [`listAudienceInsightsAttributes`](https://developers.google.com/google-ads/api/reference/rpc/v26/AudienceInsightsService/ListAudienceInsightsAttributes). This method returns
a [`ListAudienceInsightsAttributesResponse`](https://developers.google.com/google-ads/api/reference/rpc/v26/ListAudienceInsightsAttributesResponse) containing the available
attributes for the requested dimensions.

For example, if `AFFINITY_USER_INTEREST` is selected as a dimension in the
request, the method returns supported affinity audiences such as "Sports Fans"
or "Music Lovers". Other supported user interest dimensions include
`IN_MARKET_USER_INTEREST` and `LIFE_EVENT_USER_INTEREST`. You can set multiple
dimensions in a single request. For a complete list of supported dimensions, see
the [`dimensions` field reference](https://developers.google.com/google-ads/api/reference/rpc/v26/ListAudienceInsightsAttributesRequest#dimensions%5B%5D).

When searching for **Knowledge Graph entities (topics)** using the
`KNOWLEDGE_GRAPH` dimension, you must provide a string query in the
[`query_text`](https://developers.google.com/google-ads/api/reference/rpc/v26/ListAudienceInsightsAttributesRequest#query_text) field (for example, `"football and the World Cup"`).

You can optionally include [`knowledge_graph_entity_search_options`](https://developers.google.com/google-ads/api/reference/rpc/v26/KnowledgeGraphEntitySearchOptions) to
customize your topic search:

- **Filter by capabilities:** Use [`search_filter`](https://developers.google.com/google-ads/api/reference/rpc/v26/KnowledgeGraphEntitySearchOptions#search_filter) to narrow down the retrieved entities to only those supporting specific capabilities. For example, you can filter for topics supported as creator attributes by providing [`CREATOR_ATTRIBUTE`](https://developers.google.com/google-ads/api/reference/rpc/v26/InsightsKnowledgeGraphEntityCapabilitiesEnum.InsightsKnowledgeGraphEntityCapabilities#CREATOR_ATTRIBUTE) in the [`entity_capability_filters`](https://developers.google.com/google-ads/api/reference/rpc/v26/KnowledgeGraphEntitySearchOptions.SearchFilter#entity_capability_filters%5B%5D) field. Multiple capabilities can be provided and are combined with `OR` logic.
- **Retrieve all creator attributes:** Set [`get_all_creator_attributes`](https://developers.google.com/google-ads/api/reference/rpc/v26/KnowledgeGraphEntitySearchOptions#get_all_creator_attributes) to `true` to retrieve all available Knowledge Graph entities tagged as creator attributes. When using this option, the `KNOWLEDGE_GRAPH` dimension must be selected, `query_text` must be empty, and you cannot combine this option with a `search_filter`.

The attributes returned by this discoverability method can be used as inputs for
other [`AudienceInsightsService`](https://developers.google.com/google-ads/api/reference/rpc/v26/AudienceInsightsService) methods.

Each [`AudienceInsightsAttributeMetadata`](https://developers.google.com/google-ads/api/reference/rpc/v26/AudienceInsightsAttributeMetadata) object in
`ListAudienceInsightsAttributesResponse` provides a structured representation of
an audience attribute alongside descriptive properties and engagement metrics.
It includes the attribute's primary definition, display name, dimension type,
and estimated audience reach. See the
[`AudienceInsightsAttributeMetadata` reference](https://developers.google.com/google-ads/api/reference/rpc/v26/AudienceInsightsAttributeMetadata) for field
definitions.

## Generate audience definition

The [`generateAudienceDefinition`](https://developers.google.com/google-ads/api/reference/rpc/v26/AudienceInsightsService/GenerateAudienceDefinition) method translates a freeform text
description of an audience into structured audience attribute suggestions that
you can pass to downstream insight methods.

## Generate suggested targeting insights

The [`generateSuggestedTargetingInsights`](https://developers.google.com/google-ads/api/reference/rpc/v26/AudienceInsightsService/GenerateSuggestedTargetingInsights) method returns a collection of
targeting insights (such as targetable audience segments) that are relevant to
the requested audience.

You can specify the requested audience either as a structured
[`InsightsAudienceDefinition`](https://developers.google.com/google-ads/api/reference/rpc/v26/InsightsAudienceDefinition) or as a text description in
[`InsightsAudienceDescription`](https://developers.google.com/google-ads/api/reference/rpc/v26/InsightsAudienceDescription).

While [`generateAudienceCompositionInsights`](https://developers.google.com/google-ads/api/reference/rpc/v26/AudienceInsightsService/GenerateAudienceCompositionInsights) returns insights for individual
attribute segments, [`generateSuggestedTargetingInsights`](https://developers.google.com/google-ads/api/reference/rpc/v26/AudienceInsightsService/GenerateSuggestedTargetingInsights) returns bundled
suggestions of targetable Google Ads audience segments. This method helps answer
questions such as "Give me targetable audience suggestions for fathers in their
30s who enjoy fishing."

## Generate targeting suggestion metrics

The [`generateTargetingSuggestionMetrics`](https://developers.google.com/google-ads/api/reference/rpc/v26/AudienceInsightsService/GenerateTargetingSuggestionMetrics) method returns a
[`GenerateTargetingSuggestionMetricsResponse`](https://developers.google.com/google-ads/api/reference/rpc/v26/GenerateTargetingSuggestionMetricsResponse), which contains the potential
YouTube population that can be reached for each audience definition requested in
[`GenerateTargetingSuggestionMetricsRequest`](https://developers.google.com/google-ads/api/reference/rpc/v26/GenerateTargetingSuggestionMetricsRequest).

This method helps answer questions such as "How many men aged 18+ interested in
camping in the United States can be reached on YouTube?"

## Generate audience composition insights

The [`generateAudienceCompositionInsights`](https://developers.google.com/google-ads/api/reference/rpc/v26/AudienceInsightsService/GenerateAudienceCompositionInsights) method returns a
[`GenerateAudienceCompositionInsightsResponse`](https://developers.google.com/google-ads/api/reference/rpc/v26/GenerateAudienceCompositionInsightsResponse), which contains a list of
attributes that represent the requested audience of interest, along with index
and share metrics that compare each attribute's share of the audience against a
baseline population.

You must provide a target country for the audience. The list of supported
dimensions for retrieving composition insights is documented on the `dimensions`
field of [`GenerateAudienceCompositionInsightsRequest`](https://developers.google.com/google-ads/api/reference/rpc/v26/GenerateAudienceCompositionInsightsRequest).

This method helps answer questions such as "What are the top affinities my
target audience is interested in compared to the general population, and how
much more likely are they to engage with those affinities?"

## Generate audience overlap insights

The [`generateAudienceOverlapInsights`](https://developers.google.com/google-ads/api/reference/rpc/v26/AudienceInsightsService/GenerateAudienceOverlapInsights) method returns a
[`GenerateAudienceOverlapInsightsResponse`](https://developers.google.com/google-ads/api/reference/rpc/v26/GenerateAudienceOverlapInsightsResponse), which contains a list of
audience attributes with estimates of the overlap between their potential
YouTube reach and that of a primary attribute.

You must provide a target country and a primary attribute. Age range, gender,
affinity segments, and in-market segments are supported as audience dimensions.

This method helps answer questions such as "How large is the incremental
audience size when we target both sports fans and music lovers in the United
States?"

## Generate Insights Finder report

The [`generateInsightsFinderReport`](https://developers.google.com/google-ads/api/reference/rpc/v26/AudienceInsightsService/GenerateInsightsFinderReport) method creates a saved report in
[Insights Finder](https://ads.google.com/intl/en_us/home/tools/insights-finder/) based on the inputs specified in
[`GenerateInsightsFinderReportRequest`](https://developers.google.com/google-ads/api/reference/rpc/v26/GenerateInsightsFinderReportRequest) and returns a
[`GenerateInsightsFinderReportResponse`](https://developers.google.com/google-ads/api/reference/rpc/v26/GenerateInsightsFinderReportResponse) containing an externally accessible
link to open that report in the Insights Finder UI.

## Google Issue Tracker

Use Google Issue Tracker to ask support questions, report bugs, or submit
feature requests. Google tracks, prioritizes, and posts updates on your
requests directly in Issue Tracker. For more information, see [Create an issue
in Google Issue Tracker](https://developers.google.com/issue-tracker/guides/create-issue-ui).

Create an issue by using one of the following Issue Tracker templates:

- [Ask a general support question or submit documentation feedback](https://issuetracker.google.com/issues/new?component=2315943&template=2440256)
- [Report a technical bug](https://issuetracker.google.com/issues/new?component=2315943&template=2440158)
- [Submit an API feature request](https://issuetracker.google.com/issues/new?component=2315943&template=2440255)

Fill out all fields in the template with detailed information so that Google can
reproduce and prioritize your request. Google might close incomplete reports and
ask you to submit a new issue with the missing details.