You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 34c6a46
Browse filesBrowse the repository at this point in the historyBrowse files
Copy file name to clipboardExpand all lines: apps/docs/content/docs/integrations/google_ads.mdx
+24-15Lines changed: 24 additions & 15 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -12,6 +12,13 @@ import { BlockInfoCard } from "@/components/ui/block-info-card"
12
12
13
13
{/* MANUAL-CONTENT-START:intro */}
14
14
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.
15
+
16
+
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.
17
+
18
+
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.
19
+
20
+
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.
21
+
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.
15
22
{/* MANUAL-CONTENT-END */}
16
23
17
24
@@ -25,19 +32,18 @@ Connect to Google Ads to list accessible accounts, list campaigns, view ad group
25
32
26
33
### List Google Ads Customers
27
34
28
-
List all Google Ads customer accounts accessible by the authenticated user
35
+
List Google Ads accounts directly accessible by the authenticated user; query customer_client for manager subaccounts
29
36
30
37
#### Input
31
38
32
39
| Parameter | Type | Required | Description |
33
40
| --------- | ---- | -------- | ----------- |
34
-
|`developerToken`| string | Yes | Google Ads API developer token |
35
41
36
42
#### Output
37
43
38
44
| Parameter | Type | Description |
39
45
| --------- | ---- | ----------- |
40
-
|`customerIds`| array |List of accessible customer IDs|
46
+
|`customerIds`| array |Customer IDs directly accessible by the user|
41
47
|`totalCount`| number | Total number of accessible customer accounts |
42
48
43
49
### Google Ads Search (GAQL)
@@ -49,7 +55,6 @@ Run a custom Google Ads Query Language (GAQL) query
49
55
| Parameter | Type | Required | Description |
50
56
| --------- | ---- | -------- | ----------- |
51
57
|`customerId`| string | Yes | Google Ads customer ID \(numeric, no dashes\)|
52
-
|`developerToken`| string | Yes | Google Ads API developer token |
53
58
|`managerCustomerId`| string | No | Manager account customer ID \(if accessing via manager account\)|
54
59
|`query`| string | Yes | GAQL query to execute |
55
60
|`pageToken`| string | No | Page token for pagination |
@@ -58,9 +63,9 @@ Run a custom Google Ads Query Language (GAQL) query
58
63
59
64
| Parameter | Type | Description |
60
65
| --------- | ---- | ----------- |
61
-
|`results`|json|Array of result objects from the GAQL query |
62
-
|`totalResultsCount`| number | Total number of matching results|
63
-
|`nextPageToken`| string | Token for the next page of results|
66
+
|`results`|array|Rows containing only the fields selected by the GAQL query |
67
+
|`totalResultsCount`| number | Total matching rows ignoring LIMIT, when returned by Google|
68
+
|`nextPageToken`| string | Token for the next page; keep the same query and customer|
64
69
65
70
### List Google Ads Campaigns
66
71
@@ -70,8 +75,8 @@ List campaigns in a Google Ads account with optional status filtering
70
75
71
76
| Parameter | Type | Required | Description |
72
77
| --------- | ---- | -------- | ----------- |
78
+
|`pageToken`| string | No | Continuation token from the previous page; keep the same customer and query inputs |
73
79
|`customerId`| string | Yes | Google Ads customer ID \(numeric, no dashes\)|
74
-
|`developerToken`| string | Yes | Google Ads API developer token |
75
80
|`managerCustomerId`| string | No | Manager account customer ID \(if accessing via manager account\)|
76
81
|`status`| string | No | Filter by campaign status \(ENABLED, PAUSED, REMOVED\)|
77
82
|`limit`| number | No | Maximum number of campaigns to return |
@@ -80,6 +85,7 @@ List campaigns in a Google Ads account with optional status filtering
80
85
81
86
| Parameter | Type | Description |
82
87
| --------- | ---- | ----------- |
88
+
|`nextPageToken`| string | Continuation token, or null on the last page; reuse unchanged query inputs |
83
89
|`campaigns`| array | List of campaigns in the account |
84
90
| ↳ `id`| string | Campaign ID |
85
91
| ↳ `name`| string | Campaign name |
@@ -88,7 +94,7 @@ List campaigns in a Google Ads account with optional status filtering
88
94
| ↳ `startDate`| string | Campaign start date \(YYYY-MM-DD\)|
89
95
| ↳ `endDate`| string | Campaign end date \(YYYY-MM-DD\)|
90
96
| ↳ `budgetAmountMicros`| string | Daily budget in micros \(divide by 1,000,000 for currency value\)|
91
-
|`totalCount`| number |Total number of campaigns returned|
97
+
|`totalCount`| number |Number of campaigns in this page|
92
98
93
99
### Google Ads Campaign Performance
94
100
@@ -98,8 +104,8 @@ Get performance metrics for Google Ads campaigns over a date range
98
104
99
105
| Parameter | Type | Required | Description |
100
106
| --------- | ---- | -------- | ----------- |
107
+
|`pageToken`| string | No | Continuation token from the previous page; keep the same customer and query inputs |
101
108
|`customerId`| string | Yes | Google Ads customer ID \(numeric, no dashes\)|
102
-
|`developerToken`| string | Yes | Google Ads API developer token |
103
109
|`managerCustomerId`| string | No | Manager account customer ID \(if accessing via manager account\)|
104
110
|`campaignId`| string | No | Filter by specific campaign ID |
105
111
|`dateRange`| string | No | Predefined date range \(LAST_7_DAYS, LAST_30_DAYS, THIS_MONTH, LAST_MONTH, TODAY, YESTERDAY\)|
@@ -110,6 +116,7 @@ Get performance metrics for Google Ads campaigns over a date range
110
116
111
117
| Parameter | Type | Description |
112
118
| --------- | ---- | ----------- |
119
+
|`nextPageToken`| string | Continuation token, or null on the last page; reuse unchanged query inputs |
113
120
|`campaigns`| array | Campaign performance data broken down by date |
114
121
| ↳ `id`| string | Campaign ID |
115
122
| ↳ `name`| string | Campaign name |
@@ -120,7 +127,7 @@ Get performance metrics for Google Ads campaigns over a date range
120
127
| ↳ `ctr`| number | Click-through rate \(0.0 to 1.0\)|
121
128
| ↳ `conversions`| number | Number of conversions |
122
129
| ↳ `date`| string | Date for this row \(YYYY-MM-DD\)|
123
-
|`totalCount`| number |Total number of result rows |
130
+
|`totalCount`| number |Number of rows in this page|
124
131
125
132
### List Google Ads Ad Groups
126
133
@@ -130,8 +137,8 @@ List ad groups in a Google Ads campaign
130
137
131
138
| Parameter | Type | Required | Description |
132
139
| --------- | ---- | -------- | ----------- |
140
+
|`pageToken`| string | No | Continuation token from the previous page; keep the same customer and query inputs |
133
141
|`customerId`| string | Yes | Google Ads customer ID \(numeric, no dashes\)|
134
-
|`developerToken`| string | Yes | Google Ads API developer token |
135
142
|`managerCustomerId`| string | No | Manager account customer ID \(if accessing via manager account\)|
136
143
|`campaignId`| string | Yes | Campaign ID to list ad groups for |
137
144
|`status`| string | No | Filter by ad group status \(ENABLED, PAUSED, REMOVED\)|
@@ -141,14 +148,15 @@ List ad groups in a Google Ads campaign
141
148
142
149
| Parameter | Type | Description |
143
150
| --------- | ---- | ----------- |
151
+
|`nextPageToken`| string | Continuation token, or null on the last page; reuse unchanged query inputs |
144
152
|`adGroups`| array | List of ad groups in the campaign |
145
153
| ↳ `id`| string | Ad group ID |
146
154
| ↳ `name`| string | Ad group name |
147
155
| ↳ `status`| string | Ad group status \(ENABLED, PAUSED, REMOVED\)|
148
156
| ↳ `type`| string | Ad group type \(SEARCH_STANDARD, DISPLAY_STANDARD, SHOPPING_PRODUCT_ADS\)|
149
157
| ↳ `campaignId`| string | Parent campaign ID |
150
158
| ↳ `campaignName`| string | Parent campaign name |
151
-
|`totalCount`| number |Total number of ad groups returned|
159
+
|`totalCount`| number |Number of ad groups in this page|
152
160
153
161
### Google Ads Ad Performance
154
162
@@ -158,8 +166,8 @@ Get performance metrics for individual ads over a date range
158
166
159
167
| Parameter | Type | Required | Description |
160
168
| --------- | ---- | -------- | ----------- |
169
+
|`pageToken`| string | No | Continuation token from the previous page; keep the same customer and query inputs |
161
170
|`customerId`| string | Yes | Google Ads customer ID \(numeric, no dashes\)|
162
-
|`developerToken`| string | Yes | Google Ads API developer token |
163
171
|`managerCustomerId`| string | No | Manager account customer ID \(if accessing via manager account\)|
164
172
|`campaignId`| string | No | Filter by campaign ID |
165
173
|`adGroupId`| string | No | Filter by ad group ID |
@@ -172,6 +180,7 @@ Get performance metrics for individual ads over a date range
172
180
173
181
| Parameter | Type | Description |
174
182
| --------- | ---- | ----------- |
183
+
|`nextPageToken`| string | Continuation token, or null on the last page; reuse unchanged query inputs |
175
184
|`ads`| array | Ad performance data broken down by date |
176
185
| ↳ `adId`| string | Ad ID |
177
186
| ↳ `adGroupId`| string | Parent ad group ID |
@@ -185,7 +194,7 @@ Get performance metrics for individual ads over a date range
185
194
| ↳ `ctr`| number | Click-through rate \(0.0 to 1.0\)|
186
195
| ↳ `conversions`| number | Number of conversions |
187
196
| ↳ `date`| string | Date for this row \(YYYY-MM-DD\)|
188
-
|`totalCount`| number |Total number of result rows |
197
+
|`totalCount`| number |Number of rows in this page|
0 commit comments