Skip to content

fix(google-ads): align reporting with current API access #8812

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
waleedlatif1 merged 2 commits into from
Oct 8, 2026
Merged

fix(google-ads): align reporting with current API access #8812

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
ce0f018
fix(google-ads): align reporting with current API access
waleedlatif1 Oct 8, 2026
150ff9f
fix(google-ads): preserve nullable inputs and redact retired credentials
waleedlatif1 Oct 8, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .github/scripts/http-e2e.sh
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -102,6 +102,7 @@ case "$group" in
# because they finish in seconds. Self-hosted without billing: hosted billing admits runs through
# Redis, which the CLI app is not given.
cli)
GOOGLE_ADS_REPORT_PATH="$report_dir/google-ads.json" bun scripts/test-google-ads-e2e.ts
for search in google-content lucid zoom google-meet; do
report_var="SEARCH_$(echo "$search" | tr 'a-z-' 'A-Z_')_REPORT_PATH"
env NEXT_PUBLIC_APP_URL=http://127.0.0.1:3040 NEXT_PUBLIC_FORCE_HOSTED=false \
Expand Down
39 changes: 24 additions & 15 deletions apps/docs/content/docs/integrations/google_ads.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,13 @@ import { BlockInfoCard } from "@/components/ui/block-info-card"

{/* MANUAL-CONTENT-START:intro */}
Use [Google Ads](https://ads.google.com) in Sim to list accessible accounts and campaigns, retrieve ad groups and performance metrics, and run custom Google Ads Query Language (GAQL) queries. These read operations support campaign reporting and budget monitoring workflows.

Connect your Google account and select a reporting operation. Google requires the `adwords` OAuth scope even for read-only reports; Sim's Google Ads operations do not create or modify ads, budgets, or billing.

Google Ads API access belongs to the Google Cloud project that owns the OAuth client. Self-hosted deployments must enable the Google Ads API and configure the project's access level in the [Google Ads API overview](https://console.cloud.google.com/google/ads-apis/overview). Test access works only with Google Ads test accounts; production accounts require an appropriate production access level. [Developer tokens were retired on September 9, 2026](https://developers.google.com/google-ads/api/docs/api-policy/developer-token) and are no longer needed.

Use the client account's Customer ID for reports. If your Google user accesses that account through a manager, set Manager Customer ID in the additional fields. List Customers returns accounts directly accessible to the signed-in user, which may include the manager rather than its client accounts. Test accounts do not serve ads and cannot demonstrate real impressions, clicks, or spend.
All report operations return one page at a time (up to 10,000 rows). Use the returned `nextPageToken` in Page Token with unchanged query inputs to retrieve the next page. `totalCount` counts the current page. Custom Query also returns `totalResultsCount`, which ignores GAQL LIMIT. Daily performance reports return one row per entity and date; sum counts before computing ratios. Costs are in micros of the customer account currency.
{/* MANUAL-CONTENT-END */}


Expand All @@ -25,19 +32,18 @@ Connect to Google Ads to list accessible accounts, list campaigns, view ad group

### List Google Ads Customers

List all Google Ads customer accounts accessible by the authenticated user
List Google Ads accounts directly accessible by the authenticated user; query customer_client for manager subaccounts

#### Input

| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `developerToken` | string | Yes | Google Ads API developer token |

#### Output

| Parameter | Type | Description |
| --------- | ---- | ----------- |
| `customerIds` | array | List of accessible customer IDs |
| `customerIds` | array | Customer IDs directly accessible by the user |
| `totalCount` | number | Total number of accessible customer accounts |

### Google Ads Search (GAQL)
Expand All @@ -49,7 +55,6 @@ Run a custom Google Ads Query Language (GAQL) query
| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `customerId` | string | Yes | Google Ads customer ID \(numeric, no dashes\) |
| `developerToken` | string | Yes | Google Ads API developer token |
| `managerCustomerId` | string | No | Manager account customer ID \(if accessing via manager account\) |
| `query` | string | Yes | GAQL query to execute |
| `pageToken` | string | No | Page token for pagination |
Expand All @@ -58,9 +63,9 @@ Run a custom Google Ads Query Language (GAQL) query

| Parameter | Type | Description |
| --------- | ---- | ----------- |
| `results` | json | Array of result objects from the GAQL query |
| `totalResultsCount` | number | Total number of matching results |
| `nextPageToken` | string | Token for the next page of results |
| `results` | array | Rows containing only the fields selected by the GAQL query |
| `totalResultsCount` | number | Total matching rows ignoring LIMIT, when returned by Google |
| `nextPageToken` | string | Token for the next page; keep the same query and customer |

### List Google Ads Campaigns

Expand All @@ -70,8 +75,8 @@ List campaigns in a Google Ads account with optional status filtering

| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `pageToken` | string | No | Continuation token from the previous page; keep the same customer and query inputs |
| `customerId` | string | Yes | Google Ads customer ID \(numeric, no dashes\) |
| `developerToken` | string | Yes | Google Ads API developer token |
| `managerCustomerId` | string | No | Manager account customer ID \(if accessing via manager account\) |
| `status` | string | No | Filter by campaign status \(ENABLED, PAUSED, REMOVED\) |
| `limit` | number | No | Maximum number of campaigns to return |
Expand All @@ -80,6 +85,7 @@ List campaigns in a Google Ads account with optional status filtering

| Parameter | Type | Description |
| --------- | ---- | ----------- |
| `nextPageToken` | string | Continuation token, or null on the last page; reuse unchanged query inputs |
| `campaigns` | array | List of campaigns in the account |
| ↳ `id` | string | Campaign ID |
| ↳ `name` | string | Campaign name |
Expand All @@ -88,7 +94,7 @@ List campaigns in a Google Ads account with optional status filtering
| ↳ `startDate` | string | Campaign start date \(YYYY-MM-DD\) |
| ↳ `endDate` | string | Campaign end date \(YYYY-MM-DD\) |
| ↳ `budgetAmountMicros` | string | Daily budget in micros \(divide by 1,000,000 for currency value\) |
| `totalCount` | number | Total number of campaigns returned |
| `totalCount` | number | Number of campaigns in this page |

### Google Ads Campaign Performance

Expand All @@ -98,8 +104,8 @@ Get performance metrics for Google Ads campaigns over a date range

| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `pageToken` | string | No | Continuation token from the previous page; keep the same customer and query inputs |
| `customerId` | string | Yes | Google Ads customer ID \(numeric, no dashes\) |
| `developerToken` | string | Yes | Google Ads API developer token |
| `managerCustomerId` | string | No | Manager account customer ID \(if accessing via manager account\) |
| `campaignId` | string | No | Filter by specific campaign ID |
| `dateRange` | string | No | Predefined date range \(LAST_7_DAYS, LAST_30_DAYS, THIS_MONTH, LAST_MONTH, TODAY, YESTERDAY\) |
Expand All @@ -110,6 +116,7 @@ Get performance metrics for Google Ads campaigns over a date range

| Parameter | Type | Description |
| --------- | ---- | ----------- |
| `nextPageToken` | string | Continuation token, or null on the last page; reuse unchanged query inputs |
| `campaigns` | array | Campaign performance data broken down by date |
| ↳ `id` | string | Campaign ID |
| ↳ `name` | string | Campaign name |
Expand All @@ -120,7 +127,7 @@ Get performance metrics for Google Ads campaigns over a date range
| ↳ `ctr` | number | Click-through rate \(0.0 to 1.0\) |
| ↳ `conversions` | number | Number of conversions |
| ↳ `date` | string | Date for this row \(YYYY-MM-DD\) |
| `totalCount` | number | Total number of result rows |
| `totalCount` | number | Number of rows in this page |

### List Google Ads Ad Groups

Expand All @@ -130,8 +137,8 @@ List ad groups in a Google Ads campaign

| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `pageToken` | string | No | Continuation token from the previous page; keep the same customer and query inputs |
| `customerId` | string | Yes | Google Ads customer ID \(numeric, no dashes\) |
| `developerToken` | string | Yes | Google Ads API developer token |
| `managerCustomerId` | string | No | Manager account customer ID \(if accessing via manager account\) |
| `campaignId` | string | Yes | Campaign ID to list ad groups for |
| `status` | string | No | Filter by ad group status \(ENABLED, PAUSED, REMOVED\) |
Expand All @@ -141,14 +148,15 @@ List ad groups in a Google Ads campaign

| Parameter | Type | Description |
| --------- | ---- | ----------- |
| `nextPageToken` | string | Continuation token, or null on the last page; reuse unchanged query inputs |
| `adGroups` | array | List of ad groups in the campaign |
| ↳ `id` | string | Ad group ID |
| ↳ `name` | string | Ad group name |
| ↳ `status` | string | Ad group status \(ENABLED, PAUSED, REMOVED\) |
| ↳ `type` | string | Ad group type \(SEARCH_STANDARD, DISPLAY_STANDARD, SHOPPING_PRODUCT_ADS\) |
| ↳ `campaignId` | string | Parent campaign ID |
| ↳ `campaignName` | string | Parent campaign name |
| `totalCount` | number | Total number of ad groups returned |
| `totalCount` | number | Number of ad groups in this page |

### Google Ads Ad Performance

Expand All @@ -158,8 +166,8 @@ Get performance metrics for individual ads over a date range

| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `pageToken` | string | No | Continuation token from the previous page; keep the same customer and query inputs |
| `customerId` | string | Yes | Google Ads customer ID \(numeric, no dashes\) |
| `developerToken` | string | Yes | Google Ads API developer token |
| `managerCustomerId` | string | No | Manager account customer ID \(if accessing via manager account\) |
| `campaignId` | string | No | Filter by campaign ID |
| `adGroupId` | string | No | Filter by ad group ID |
Expand All @@ -172,6 +180,7 @@ Get performance metrics for individual ads over a date range

| Parameter | Type | Description |
| --------- | ---- | ----------- |
| `nextPageToken` | string | Continuation token, or null on the last page; reuse unchanged query inputs |
| `ads` | array | Ad performance data broken down by date |
| ↳ `adId` | string | Ad ID |
| ↳ `adGroupId` | string | Parent ad group ID |
Expand All @@ -185,7 +194,7 @@ Get performance metrics for individual ads over a date range
| ↳ `ctr` | number | Click-through rate \(0.0 to 1.0\) |
| ↳ `conversions` | number | Number of conversions |
| ↳ `date` | string | Date for this row \(YYYY-MM-DD\) |
| `totalCount` | number | Total number of result rows |
| `totalCount` | number | Number of rows in this page |

## OAuth Scopes

Expand Down
Loading
Loading