> ## Documentation Index
> Fetch the complete documentation index at: https://docs.permutive.com/llms.txt
> Use this file to discover all available pages before exploring further.
# GAM API Usage
> How Permutive uses the Google Ad Manager reporting API for campaign optimization and insights
## Overview
Google Ad Manager (GAM) is the most common ad server amongst top publishers. Permutive uses the GAM reporting API to provide campaign metadata, metrics, and recommendations across our Planning and Optimization products. This guide explains how we use GAM data and the permissions required to support this integration.
## Why Permutive Uses the GAM Reporting API
When analyzing campaigns to identify optimization opportunities or share insights reports with advertisers, having context around campaign delivery and performance is critical. While Permutive's value lies in surfacing additional insights about users who engaged with a campaign based on first-party data, the ability to see actual impressions, clicks, and other metrics is essential for optimization use cases.
### Key Benefits
**Improved user experience** — Ingesting order names, flight dates, and other attributes allows Permutive to display campaign information directly in the UI without manual data entry.
**Campaign context** — View actual delivery and performance metrics within the Permutive UI alongside audience insights.
**Cohort targeting analysis** — Understand which cohorts are actually targeted for a campaign and how they are performing. This is a valuable data point for users and an essential component for informing optimization recommendations.
**Non-targeted cohort potential** — Analyze performance for all cohorts present when an impression was delivered, even if they weren't directly targeted. This powers the AI recommendations in Optimization.
## Data Collection and Usage
Permutive has developed a comprehensive automated process for extracting reporting from the GAM API across customers. The ability to automate data ingestion and visualization is a valuable upgrade for customers, as this level of reporting would otherwise be highly time-consuming across all campaigns.
### What We Collect
Due to different restrictions and limitations around how certain report dimensions and metrics can be combined, we pull multiple reports via the API to support various product use cases:
| Report Type | Description | Use Case |
| :------------------- | :--------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------- |
| Order Information | Key metadata for orders and line items with associated aggregated metrics | Displaying order information in the UI and providing accurate, de-duplicated KPIs |
| Targeted Cohorts | Delivery (impressions) and performance metrics (clicks, viewability) broken down by targeted cohorts | Understanding the target audience and displaying cohort performance data |
| Non-targeted Cohorts | Impressions and performance metrics for cohorts not explicitly targeted | Analyzing potential performance of cohorts for optimization recommendations |
### Data Ingestion Process
* Data is ingested at **daily intervals** for the previous completed day
* **Maximum 24-hour delay** for data to appear in Permutive
* No personal information is stored
* All data is stored in EU BigQuery
### Reconciliation and Accuracy
* Automated alerts when a report fails or there are gaps in the data
* Roll-up metrics are reconciled against day-level reports to ensure accuracy
## Permissions Required
The permissions outlined below are required to support all current integration use cases, including cohort activation and campaign optimization.
### Permission Configuration
#### Access the Interface
| Permission | Required |
| :---------- | :------- |
| Admin | No |
| Ad Exchange | Yes |
| Billing | No |
| Delivery | Yes |
| Overview | Yes |
#### Define and Deliver Ads
| Permission | Required | Notes |
| :----------------------------------- | :------- | :------------------------------------------------------------ |
| Ad units, placements, and key-values | Yes | All Permutive-related key-values need to be set as reportable |
| Audience segments | No | |
| Audience segments (third-party) | No | |
| Orders and line items | Yes | If Teams are used, Permutive needs to be assigned accordingly |
| Yield groups | Yes | |
#### Policy and Protections
| Permission | Required |
| :------------------------------- | :------- |
| Privacy and messaging | No |
| EU user consent and CCPA setting | No |
#### Reports
| Permission | Required |
| :-------------------- | :------- |
| Ad exchange reports | Yes |
| Ad manager reports | Yes |
| Opportunities reports | No |
| Teams reports | No |
#### Sales
| Permission | Required |
| :-------------------- | :------- |
| Sales proposals | No |
| Buyer sales proposals | No |
#### User Network Settings
| Permission | Required |
| :------------- | :------- |
| Change history | Yes |
#### Video Solutions
| Permission | Required |
| :--------- | :------- |
| Ad rules | No |
### Teams Configuration
In addition to the permissions above, for customers using the Teams functionality for managing user access, you must ensure that Permutive has access to all ad units and other inventory types.
If Teams are used in GAM, the Permutive service account ([dfp@permutive.com](mailto:dfp@permutive.com)) must be assigned to appropriate teams to access order and line item data.
## How to Check Permissions
### Permission Check Endpoint
Permutive can run an automated permission check that tests whether the service account has sufficient access to run line-item level reports. This check validates if there are sufficient permissions to extract data from the GAM report service.
The permission check:
1. Runs test reports with different dimensions
2. Determines if line-item level reporting is possible
3. Identifies specific permission gaps if issues are found
If line-item level reports return no impressions but other granularity levels work, it indicates insufficient permissions.
### Requesting a Permission Check
Contact your Customer Success Manager (CSM) to request a permission check for your GAM network. They can verify:
* Whether the Permutive service account has the required permissions
* Specific permissions that may be missing
* Teams configuration issues that could affect access
## Troubleshooting Permissions
If campaigns are not appearing in Optimization despite having the integration set up:
1. Verify all required permissions are granted (see table above)
2. Check that Permutive-related key-values are set as reportable
3. If using Teams, ensure Permutive is assigned to the appropriate teams
4. Request a permission check from your Customer Success Manager (CSM)
If order-level data appears but line item data is missing:
1. Verify the "Orders and line items" permission is granted
2. Check Teams configuration if applicable
3. Ensure the Permutive service account has access to all relevant ad units
If you have multiple GAM network codes:
1. Each network requires separate permission configuration
2. Permissions must be granted in each GAM network individually
3. Some campaigns may appear for one network but not another if permissions differ
If data appears stale or is not updating:
1. Data is ingested daily, so expect up to 24-hour delay
2. Check if there are any reported outages or ingestion failures
3. Contact support if data hasn't updated for more than 48 hours
## Related Documentation
* [Optimization Product Documentation](/products/workflows-insights/optimization) — Learn how to use campaign optimization features
* [Google Ad Manager Integration](/integrations/advertising/ad-servers/google-ad-manager) — Set up the GAM integration for cohort activation
* [Google Support Documentation](https://support.google.com/admanager/answer/9154293) — Official GAM permissions documentation