# Google Ads (/integrations/google_ads)





{/* 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 */}

## OAuth scopes [#oauth-scopes]

Sim requests these scopes when someone connects a Google Ads account. For a self-hosted deployment, register your own app with the provider using the settings below. See [Integrations and OAuth](/platform/self-hosting/integrations-oauth) for setup.

| Setting | Value |
| - | - |
| Redirect URI | `<NEXT_PUBLIC_APP_URL>/api/auth/oauth2/callback/google-ads` |
| Environment variables | `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET` |

| Scope | Description |
| - | - |
| `https://www.googleapis.com/auth/userinfo.email` | View email address |
| `https://www.googleapis.com/auth/userinfo.profile` | View basic profile info |
| `https://www.googleapis.com/auth/adwords` | Manage Google Ads campaigns and reporting |

## Use the block [#usage-instructions]

Connect to Google Ads to list accessible accounts, list campaigns, view ad group details, get performance metrics, and run custom GAQL queries.

## Actions [#actions]

### List Google Ads Customers [#list-google-ads-customers]

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

#### Input [#input]

| Parameter | Type | Required | Description |
| - | - | - | - |

#### Output [#output]

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

### Google Ads Search (GAQL) [#google-ads-search-gaql]

Run a custom Google Ads Query Language (GAQL) query

#### Input [#input-1]

| Parameter | Type | Required | Description |
| - | - | - | - |
| `customerId` | string | Yes | Google Ads customer ID (numeric, no dashes) |
| `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 |

#### Output [#output-1]

| Parameter | Type | Description |
| - | - | - |
| `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 [#list-google-ads-campaigns]

List campaigns in a Google Ads account with optional status filtering

#### Input [#input-2]

| 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) |
| `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 |

#### Output [#output-2]

| 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 |
| ↳ `status` | string | Campaign status (ENABLED, PAUSED, REMOVED) |
| ↳ `channelType` | string | Advertising channel type (SEARCH, DISPLAY, SHOPPING, VIDEO, PERFORMANCE\_MAX) |
| ↳ `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 | Number of campaigns in this page |

### Google Ads Campaign Performance [#google-ads-campaign-performance]

Get performance metrics for Google Ads campaigns over a date range

#### Input [#input-3]

| 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) |
| `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) |
| `startDate` | string | No | Custom start date in YYYY-MM-DD format |
| `endDate` | string | No | Custom end date in YYYY-MM-DD format |

#### Output [#output-3]

| 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 |
| ↳ `status` | string | Campaign status |
| ↳ `impressions` | string | Number of impressions |
| ↳ `clicks` | string | Number of clicks |
| ↳ `costMicros` | string | Cost in micros (divide by 1,000,000 for currency value) |
| ↳ `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 | Number of rows in this page |

### List Google Ads Ad Groups [#list-google-ads-ad-groups]

List ad groups in a Google Ads campaign

#### Input [#input-4]

| 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) |
| `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) |
| `limit` | number | No | Maximum number of ad groups to return |

#### Output [#output-4]

| 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 | Number of ad groups in this page |

### Google Ads Ad Performance [#google-ads-ad-performance]

Get performance metrics for individual ads over a date range

<ReferenceDetails>
  #### Input [#input-5]

  | 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) |
  | `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 |
  | `dateRange` | string | No | Predefined date range (LAST\_7\_DAYS, LAST\_30\_DAYS, THIS\_MONTH, LAST\_MONTH, TODAY, YESTERDAY) |
  | `startDate` | string | No | Custom start date in YYYY-MM-DD format |
  | `endDate` | string | No | Custom end date in YYYY-MM-DD format |
  | `limit` | number | No | Maximum number of results to return |

  #### Output [#output-5]

  | 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 |
  | ↳ `adGroupName` | string | Parent ad group name |
  | ↳ `campaignId` | string | Parent campaign ID |
  | ↳ `campaignName` | string | Parent campaign name |
  | ↳ `adType` | string | Ad type (RESPONSIVE\_SEARCH\_AD, EXPANDED\_TEXT\_AD, etc.) |
  | ↳ `impressions` | string | Number of impressions |
  | ↳ `clicks` | string | Number of clicks |
  | ↳ `costMicros` | string | Cost in micros (divide by 1,000,000 for currency value) |
  | ↳ `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 | Number of rows in this page |
</ReferenceDetails>