Ad groups

An ad group is a strategy that falls within a particular campaign and enables you to assemble targeting strategies to specify when, where, and how to serve ads. You can manage budgets, goals, creatives, site lists, inventory, and viewability, as well as targeting options for audiences, devices, locations, languages, times of day, and video adjustments across ad groups.

This guide covers the settings that apply to every ad group, such as funnel location, goals, and performance-enhancing features. For the end-to-end process (creating, associating creatives and bid lists, allocating budget, and updating), see Ad group creation workflows.

Here's what you need to know about ad groups:

• You can use both the GraphQL and REST API to create and manage your ad groups. For details on what each API supports, see GraphQL and REST API comparison.
• To create or update multiple ad groups at once, you must use GraphQL API bulk operations.
• To enable an ad group, it must be associated with a campaign and have at least one approved creative. While you can create an ad group with an empty CreativeIds array, you cannot enable it until you upload a creative.
• Ad group budget allocation and pacing are set at the campaign level, and only in GraphQL. For details, see Budget allocation.
• If a campaign is in Kokai and has the Sellers and Publishers 500+ (SP500+) marketplace enabled, any ad group you create in that campaign automatically inherits SP500+ access.

Setup and optimization

The following table lists the properties you must include in all ad groups.

You can further optimize ad groups using performance-enhancing features such as Predictive Clearing and Identity Alliance. Here's what else you need to know about setting up ad groups:

• To configure and manage ad group budgets, you must use GraphQL. For details on budget types and pacing options, see Budget allocation.
• By default, ad groups have no budget allocation, allowing the platform algorithm to distribute flight budget wherever it identifies the greatest value.
• Any budget manually allocated to ad groups through the minimumSpendInAdvertiserCurrency flight property is automatically reserved, regardless of whether the ad groups are enabled and eligible to spend (isEnabled property).

GraphQL and REST API comparison

To create, update, or query ad groups, you can use the GraphQL and REST API. The following table lists the differences between the GraphQL and REST API and how many ad groups you can create, update, and query per call.

NOTE: The update and create mutations for individual ad groups are not fully featured yet. Check for updates as we roll out new features and enhancements.

TIP: For comprehensive steps from creating an ad group through associating creatives, bid lists, and budget, see Ad group creation workflows.

Funnel location

An ad group funnel location identifies the focus or objective of your ad group (awareness, consideration, and conversion). For example, you may want to focus on getting people to consider your business, encourage them to make a purchase, or sign up for an event.

To measure the success of your ad groups effectively, you must set the FunnelLocation value when you create your ad group:

Performance-enhancing features

Here's what you need to know about performance-enhancing features for ad groups:

• To enable a feature, set the corresponding property value to true. For an example of an ad group with some of the key performance-enhancing features turned on, see the REST API request example.
• All feature properties, except Predictive Clearing and Koa Optimizations, are part of the RTBAttributes.AudienceTargeting object.
• Some features, like Audience Booster, apply only to ad groups with certain KPIs. Other features are mutually exclusive as noted in the feature and property descriptions.

The following table lists performance-enhancing features available for ad groups. The list indicates the ad group API settings for each feature and provides links to the Knowledge Portal pages and other resources where you can learn more.

TIP: For an example of an ad group with some of the key performance-enhancing features turned on, see Request example.

Look up ad groups

You can retrieve ad group details using GraphQL. The following sections provide a list of sample queries that retrieve ad group information.

• Look up ad groups by name
• Look up campaign data for an ad group
• Look up ad group performance metrics by date range
• Look up ad groups for multiple advertiser IDs
• Look up invisible or disabled ad groups
• Look up ad group settings
• Look up ad group Prism setting
• Look up ad group metadata

TIP: You can also run multiple queries at once. For details, see GraphQL bulk operations: Queries.

Look up ad groups by name

The following GraphQL query retrieves ad groups by name. You can configure the query to reduce or change the types of data returned. Other options include omitting the partner ID, searching across multiple advertisers, and combining search terms using the "and" operator.

If you have more than 100 items in your search results, use pagination to return them.

query GetAdGroupsByNameExample {
    adGroups(
        first: 100
        where: {
            partnerId: { eq: "PARTNER_ID_PLACEHOLDER" }
            advertiserId: { eq: "ADVERTISER_ID_PLACEHOLDER" }
            name: { contains: "SEARCH_TERM_PLACEHOLDER" }
        }
    ) {
        nodes {
            id
            name
            isArchived
            budget {
                currentFlightBudget
                isFluid
                total
            }
            adGroupFlights {
                nodes {
                    campaignFlightId
                    budgetInImpressions
                    dailyTargetInAdvertiserCurrency
                    dailyTargetInImpressions
                    historicalProjectedSpendInAdvertiserCurrency
                    minimumSpendInAdvertiserCurrency
                    totalSpendSoFarInAdvertiserCurrency
                    yesterdayImpressions
                    yesterdaysPotentialSpendInAdvertiserCurrency
                    yesterdaysSpendInAdvertiserCurrency
                }
            }
        }
    }
}

Look up campaign data for an ad group

The following GraphQL query retrieves campaign-level data for an ad group.

query GetCampaignKeyMetricDataForAdGroupExample {
    adGroup(id: "abc1234") {
        adGroupFlights {
            totalCount
            nodes {
                adGroupId
                forecast {
                    projectedSpend
                    relevance
                    confidence
                    lastUpdated
                }
            }
        }
        spend {
            spend
        }
    }
}

Look up ad group performance metrics by date range

With the GraphQL API, you can create and customize adGroup queries and include reporting fields that provide key performance metrics for tracking KPIs, cost and bidding, media quality, and overall effectiveness. You can either retrieve lifetime data or organize it by day or hour to help analyze trends, optimize bids, and measure engagement effectively. Whether you're evaluating media efficiency or optimizing your bidding strategy, these detailed performance metrics can help you make informed, data-driven decisions.

TIP: You can also use the reporting field to retrieve performance metrics at the advertiser and campaign level.

Here's what you need to know about looking up ad group performance metrics by date range:

• You can filter the metrics only by date.
• If you don't include a date range in the where filter, the query returns the ad group's lifetime metrics.
• You can retrieve metrics at the following time intervals, specified in the dimensions field:
  • Hourly (last 30 days)
  • Daily (last year)
• If you don’t include the dimensions field, the query returns aggregated totals for each metric without grouping data by time interval.

The following adGroup GraphQL query retrieves all metrics you can use to optimize campaign performance, manage spend and bidding, and so on. The date range is specified using gte (start, inclusive) and lt (end, exclusive) for the reporting period.

query GetAdGroupPerformanceMetricsbyDateRangeExample($adGroupId: ID!) {
  adGroup(id: $adGroupId) {
    reporting {
      generalReporting(
        where: { date: { gte: "2025-02-01", lt: "2025-03-01" } }
      ) {
        nodes {
          dimensions {
            time {
              day
            }
          }
          metrics {
            adPlays
            bids
            clicks
            conversions
            cpa {
              advertiserCurrency
            }
            cpc {
              advertiserCurrency
            }
            cpcv {
              advertiserCurrency
            }
            cpm {
              advertiserCurrency
            }
            ctr
            customCpa {
              advertiserCurrency
            }
            customRoas {
              advertiserCurrency
            }
            impressions
            revenue
            roas {
              advertiserCurrency
            }
            spend {
              advertiserCurrency
            }
            tvQualityCpm {
              advertiserCurrency
            }
            tvQualityIndex
            vCpm {
              advertiserCurrency
            }
            videoCompletionRate
            viewability
            winRate
          }
        }
      }
    }
  }
}

Look up ad groups for multiple advertiser IDs

The following GraphQL query retrieves the name and ID for ad groups across three advertisers.

query GetAdGroupForMultipleAdvertiserIdsExample {
  adGroups(where: { advertiserId: { in: ["ADVERTISER_ID__PLACEHOLDER_1", "ADVERTISER_ID__PLACEHOLDER_2", "ADVERTISER_ID__PLACEHOLDER_3"] } }) {
    nodes {
      id
      name
    }
  }
}

Look up invisible or disabled ad groups

The following GraphQL query retrieves the names, IDs, visibility, and statuses of ad groups that are either disabled or invisible across three different advertisers.

query GetInvisibleOrDisabledAdGroupsExample {
  adGroups(
    where: {
      and: {
        advertiserId: {
          in: ["ADVERTISER_ID__PLACEHOLDER_1", "ADVERTISER_ID__PLACEHOLDER_2", "ADVERTISER_ID__PLACEHOLDER_3"]
        }
        or: { isEnabled: { eq: false }, isVisible: { eq: false } }
      }
    }
  ) {
    edges {
      cursor
      node {
        id
        name
        isVisible
        isEnabled
      }
    }
    pageInfo {
      endCursor
      hasNextPage
      hasPreviousPage
      startCursor
    }
  }
}

Look up ad group settings

The following GraphQL query retrieves the ad group settings.

query GetAdGroupSettingsExample($adGroupId: ID!) {
  adGroup(id: $adGroupId) {
    id
    name
    KoaSettings {
      areFutureFeaturesEnabled
      areFutureFeaturesEnabledForPartner
      optimizationsVersion
    }
    industryCategory {
      id
      name
      parentCategoryId
      isDefault
      isSensitive
    }
    availableIndustryCategories {
      id
      name
      parentCategoryId
      isDefault
      isSensitive
    }
  }
}

Look up ad group Prism setting

The following GraphQL query checks whether Prism is available and enabled for an ad group.

query GetAdGroupPrism ($adGroupId: ID!) {
  adGroup(id: $adGroupId) {
    audienceSettings {
        dataSettings {
            prism {
                isEnabled
            }
        }
    }
  }
}

Look up ad group metadata

The following GraphQL query retrieves Ad Group (Ag) tile metadata from the UI programmatic table.

query GetAdGroupTileMetadataExample ($adGroupId: ID!) {
  adGroup(id: $adGroupId) {
    id
    name
    programmaticTiles {
      isUserOptimized
      metadataSummaries
      type
    }
  }
}

Common issues

The following table lists the common issues that prevent ad group spend and recommends possible solutions.

FAQs

How can I improve the user experience using the ad group endpoints?

For an improved user experience, integrate our API endpoints with your client-based UI. For example, you can clone and manage campaigns and ad groups in the backend, and then use our API endpoints for adjusting budgets and bid lists on a daily basis within your UI.

How can I automatically opt cloned ad groups into my current marketplace?

In GraphQL, use the DefaultUseInventoryMarketPlace property. It enables campaigns to automatically opt cloned ad groups into your current marketplace. For details, see Automatically opt cloned ad groups into marketplace.

What happens if I don't set my ad group KPIs in a campaign that has multiple goals?

The primary campaign goal becomes the default KPI for all ad groups in the campaign.

What happens if the channels in the ad group and campaign do not match?

When ad group and campaign channels are mismatched, only the ad group's channel is used for bidding.

For best practices, be sure ad groups have the same value in their ChannelId properties as the channel of the parent campaign. To target multiple channels and use the same campaign settings, clone the campaign and update the channel for the new copy of the campaign. For details, see Channels.

Can I allocate the budget during ad group creation?

No. You can use only the campaignBudgetSettingsUpdate mutation to allocate the budget, and only after you have created the ad group. For details, see Update campaign budget and other settings.

How do I use GraphQL to associate an ad group to a new campaign flight?

Use the campaignFlightUpdate mutation. For an example, see Update a campaign flight.

Can I enable Prism for all ad groups?

Yes. For details, see Prism.