# Google Ads

> Query your Google Ads account data including campaigns, ad groups, keywords, and performance metrics using the Google Ads API and GAQL (Google Ads Query Language).

Source: https://cotera.co/docs/reference/tools/individual-tools/google-ads

---

**Authentication Type:** OAuth2 + Developer Token
**Description:** Query your Google Ads account data including campaigns, ad groups, keywords, and performance metrics using the Google Ads API and GAQL (Google Ads Query Language).

***

## Authentication

To authenticate with Google Ads, you need OAuth2 credentials and a Google Ads developer token:

1. Go to the [Google Cloud Console](https://console.cloud.google.com/) and create a project (or use an existing one)
2. Enable the **Google Ads API** in the [API Library](https://console.cloud.google.com/apis/library/googleads.googleapis.com)
3. Create OAuth2 credentials (type: **Web application**) in [Credentials](https://console.cloud.google.com/apis/credentials)
4. Get a **Developer Token** from your Google Ads Manager Account under **Tools & Settings > API Center**

You'll need to provide:

* **clientId** `string`: Your OAuth2 client ID from Google Cloud Console
* **clientSecret** `string`: Your OAuth2 client secret
* **refreshToken** `string`: An OAuth2 refresh token with Google Ads access scope
* **developerToken** `string`: Your Google Ads API developer token (from the MCC API Center)

> **Note:** The developer token is separate from your OAuth credentials. You get it from your Google Ads Manager (MCC) account, not from Google Cloud Console. Test accounts have a test developer token with limited access.

***

## Account

### List Accessible Customers

List all Google Ads customer accounts accessible to the authenticated user. Use this to discover available account IDs before querying campaigns or running GAQL queries.

**Operation Type:** Query (Read)

**Parameters:**

No parameters required.

**Returns:**

* **customerIds** `array of strings`: List of accessible customer resource names (e.g., `"customers/1234567890"`)

**Example Usage:**

```json
{}
```

***

## Campaigns

### List Campaigns

List all campaigns for a Google Ads account with performance metrics including impressions, clicks, conversions, and cost. Supports filtering by date range and campaign status.

**Operation Type:** Query (Read)

**Parameters:**

* **clientCustomerId** `string` (required): The client customer ID (account to query). Remove dashes, e.g., `"6665554444"`.
* **managerCustomerId** `string` (nullable): The manager (MCC) customer ID. Required if accessing a sub-account through a manager account.
* **dateRange** `string` (nullable): Date range filter for metrics. Options: `TODAY`, `YESTERDAY`, `LAST_7_DAYS`, `LAST_BUSINESS_WEEK`, `THIS_MONTH`, `LAST_MONTH`, `LAST_14_DAYS`, `LAST_30_DAYS`. Null for all time.
* **campaignStatus** `string` (nullable): Filter by campaign status. Options: `ENABLED`, `PAUSED`, `REMOVED`. Null for all statuses.

**Returns:**

* **campaigns** `array of objects`: Array of campaigns with performance metrics
  * **id** `string`: Campaign ID
  * **name** `string`: Campaign name
  * **status** `string`: Campaign status (`ENABLED`, `PAUSED`, `REMOVED`)
  * **advertisingChannelType** `string` (nullable): Channel type (`SEARCH`, `DISPLAY`, `VIDEO`, etc.)
  * **advertisingChannelSubType** `string` (nullable): Channel sub-type
  * **optimizationScore** `number` (nullable): Optimization score (0 to 1)
  * **budgetAmountMicros** `string` (nullable): Budget amount in micros (divide by 1,000,000 for actual value)
  * **budgetPeriod** `string` (nullable): Budget period (`DAILY`, etc.)
  * **impressions** `string` (nullable): Number of impressions
  * **interactions** `string` (nullable): Number of interactions (clicks)
  * **interactionRate** `number` (nullable): Interaction rate
  * **averageCost** `string` (nullable): Average cost in micros
  * **costMicros** `string` (nullable): Total cost in micros
  * **conversions** `number` (nullable): Number of conversions
  * **costPerConversion** `number` (nullable): Cost per conversion in micros
  * **conversionsFromInteractionsRate** `number` (nullable): Conversion rate from interactions
  * **videoViews** `string` (nullable): Number of video views
  * **averageCpm** `number` (nullable): Average CPM in micros
  * **ctr** `number` (nullable): Click-through rate

**Example Usage:**

```json
{
  "clientCustomerId": "1234567890",
  "managerCustomerId": "9876543210",
  "dateRange": "LAST_30_DAYS",
  "campaignStatus": "ENABLED"
}
```

> **Tip:** Budget and cost fields are returned in micros. Divide by 1,000,000 to get the actual currency value. For example, `5000000` micros = `$5.00`.

***

### Get Campaign

Get a specific Google Ads campaign by ID with performance metrics including impressions, clicks, conversions, and cost.

**Operation Type:** Query (Read)

**Parameters:**

* **clientCustomerId** `string` (required): The client customer ID (account to query). Remove dashes, e.g., `"6665554444"`.
* **managerCustomerId** `string` (nullable): The manager (MCC) customer ID. Required if accessing through a manager account.
* **campaignId** `string` (required): The ID of the campaign to retrieve.

**Returns:**

* **campaign** `object` (nullable): The campaign details, or null if not found. Has the same fields as campaigns in the List Campaigns response.

**Example Usage:**

```json
{
  "clientCustomerId": "1234567890",
  "managerCustomerId": "9876543210",
  "campaignId": "12345678"
}
```

***

### Search with GAQL

Execute a custom Google Ads Query Language (GAQL) query against a Google Ads account. This is the most flexible tool, supporting queries across campaigns, ad groups, ads, keywords, and any other Google Ads resource.

**Operation Type:** Query (Read)

**Parameters:**

* **clientCustomerId** `string` (required): The client customer ID (account to query). Remove dashes, e.g., `"6665554444"`.
* **managerCustomerId** `string` (nullable): The manager (MCC) customer ID. Required if accessing through a manager account.
* **query** `string` (required): A Google Ads Query Language (GAQL) query.

**Returns:**

* **results** `array`: Array of result rows from the GAQL query. Structure depends on the fields selected in the query.

**Example Usage:**

```json
{
  "clientCustomerId": "1234567890",
  "query": "SELECT campaign.id, campaign.name, metrics.impressions, metrics.clicks FROM campaign WHERE campaign.status = 'ENABLED' AND segments.date DURING LAST_7_DAYS"
}
```

> **GAQL Reference:** You can query any resource in the Google Ads API, including `campaign`, `ad_group`, `ad_group_ad`, `keyword_view`, `search_term_view`, `geographic_view`, and more. See the [Google Ads Query Language documentation](https://developers.google.com/google-ads/api/docs/query/overview) for the full list of resources and fields.

### Update Campaign Status

Enable, pause, or remove a campaign by updating its status.

**Operation Type:** Mutation (Write)

**Parameters:**

* **clientCustomerId** `string` (required): The client customer ID (account to modify). Remove dashes, e.g., `"6665554444"`.
* **managerCustomerId** `string` (nullable): The manager (MCC) customer ID. Required if accessing through a manager account.
* **campaignId** `string` (required): The ID of the campaign to update.
* **status** `string` (required): The new campaign status. Options: `ENABLED`, `PAUSED`, `REMOVED`.

**Returns:**

* **success** `boolean`: Whether the status was updated successfully
* **campaignId** `string`: The campaign ID that was updated
* **newStatus** `string`: The new status of the campaign

**Example Usage:**

```json
{
  "clientCustomerId": "1234567890",
  "campaignId": "12345678",
  "status": "PAUSED"
}
```

***

## Ad Groups

### List Ad Groups

List all ad groups within a campaign or account with performance metrics.

**Operation Type:** Query (Read)

**Parameters:**

* **clientCustomerId** `string` (required): The client customer ID. Remove dashes.
* **managerCustomerId** `string` (nullable): The manager (MCC) customer ID.
* **campaignId** `string` (nullable): Filter ad groups by campaign ID. Null returns ad groups across all campaigns.
* **adGroupStatus** `string` (nullable): Filter by status. Options: `ENABLED`, `PAUSED`, `REMOVED`.
* **dateRange** `string` (nullable): Date range for metrics. Options: `TODAY`, `YESTERDAY`, `LAST_7_DAYS`, `LAST_30_DAYS`, `THIS_MONTH`, `LAST_MONTH`.

**Returns:**

* **adGroups** `array of objects`: Array of ad groups with metrics
  * **id** `string`: Ad group ID
  * **name** `string`: Ad group name
  * **status** `string`: Ad group status
  * **campaignId** `string`: Parent campaign ID
  * **campaignName** `string` (nullable): Parent campaign name
  * **type** `string` (nullable): Ad group type
  * **impressions** `string` (nullable): Number of impressions
  * **clicks** `string` (nullable): Number of clicks
  * **costMicros** `string` (nullable): Total cost in micros
  * **conversions** `number` (nullable): Number of conversions
  * **ctr** `number` (nullable): Click-through rate

**Example Usage:**

```json
{
  "clientCustomerId": "1234567890",
  "campaignId": "12345678",
  "adGroupStatus": "ENABLED",
  "dateRange": "LAST_30_DAYS"
}
```

### Get Ad Group

Get a specific ad group by ID with performance metrics.

**Operation Type:** Query (Read)

**Parameters:**

* **clientCustomerId** `string` (required): The client customer ID. Remove dashes.
* **managerCustomerId** `string` (nullable): The manager (MCC) customer ID.
* **adGroupId** `string` (required): The ID of the ad group to retrieve.

**Returns:**

* **adGroup** `object` (nullable): The ad group details with the same fields as List Ad Groups.

**Example Usage:**

```json
{
  "clientCustomerId": "1234567890",
  "adGroupId": "123456789"
}
```

***

## Ads

### List Ads

List ads within a campaign or ad group with creative details and performance metrics.

**Operation Type:** Query (Read)

**Parameters:**

* **clientCustomerId** `string` (required): The client customer ID. Remove dashes.
* **managerCustomerId** `string` (nullable): The manager (MCC) customer ID.
* **campaignId** `string` (nullable): Filter by campaign ID.
* **adGroupId** `string` (nullable): Filter by ad group ID.
* **dateRange** `string` (nullable): Date range for metrics.

**Returns:**

* **ads** `array of objects`: Array of ads with metrics
  * **id** `string`: Ad ID
  * **adGroupId** `string`: Parent ad group ID
  * **adGroupName** `string` (nullable): Parent ad group name
  * **campaignId** `string`: Parent campaign ID
  * **campaignName** `string` (nullable): Parent campaign name
  * **type** `string` (nullable): Ad type (RESPONSIVE\_SEARCH\_AD, etc.)
  * **status** `string`: Ad status
  * **headlines** `array of strings` (nullable): RSA headlines
  * **descriptions** `array of strings` (nullable): RSA descriptions
  * **finalUrls** `array of strings` (nullable): Landing page URLs
  * **impressions** `string` (nullable): Number of impressions
  * **clicks** `string` (nullable): Number of clicks
  * **costMicros** `string` (nullable): Total cost in micros
  * **conversions** `number` (nullable): Number of conversions
  * **ctr** `number` (nullable): Click-through rate

**Example Usage:**

```json
{
  "clientCustomerId": "1234567890",
  "adGroupId": "123456789",
  "dateRange": "LAST_7_DAYS"
}
```

***

## Keywords

### List Keywords

List keywords within a campaign or ad group with match types, quality scores, and performance metrics.

**Operation Type:** Query (Read)

**Parameters:**

* **clientCustomerId** `string` (required): The client customer ID. Remove dashes.
* **managerCustomerId** `string` (nullable): The manager (MCC) customer ID.
* **campaignId** `string` (nullable): Filter by campaign ID.
* **adGroupId** `string` (nullable): Filter by ad group ID.
* **keywordStatus** `string` (nullable): Filter by status. Options: `ENABLED`, `PAUSED`, `REMOVED`.
* **dateRange** `string` (nullable): Date range for metrics.

**Returns:**

* **keywords** `array of objects`: Array of keywords with metrics
  * **criterionId** `string`: Keyword criterion ID
  * **keyword** `string`: The keyword text
  * **matchType** `string`: Match type (EXACT, PHRASE, BROAD)
  * **status** `string`: Keyword status
  * **adGroupId** `string`: Parent ad group ID
  * **adGroupName** `string` (nullable): Parent ad group name
  * **campaignId** `string`: Parent campaign ID
  * **campaignName** `string` (nullable): Parent campaign name
  * **impressions** `string` (nullable): Number of impressions
  * **clicks** `string` (nullable): Number of clicks
  * **costMicros** `string` (nullable): Total cost in micros
  * **conversions** `number` (nullable): Number of conversions
  * **ctr** `number` (nullable): Click-through rate
  * **averageCpc** `string` (nullable): Average CPC in micros
  * **qualityScore** `number` (nullable): Quality score (1-10)

**Example Usage:**

```json
{
  "clientCustomerId": "1234567890",
  "campaignId": "12345678",
  "keywordStatus": "ENABLED",
  "dateRange": "LAST_30_DAYS"
}
```

***

## Common Use Cases

**Campaign Performance Monitoring:**

* Pull daily/weekly performance metrics for all active campaigns
* Track key metrics like CPA, ROAS, and conversion rates over time
* Compare campaign performance across different date ranges

**Ad Spend Analysis:**

* Monitor budget utilization across campaigns
* Identify campaigns with high spend but low conversions
* Calculate aggregate spend across multiple accounts

**Custom Reporting with GAQL:**

* Build custom reports querying ad groups, keywords, or search terms
* Analyze geographic performance with location-based queries
* Pull device-level or audience segment data for deeper analysis

**Multi-Account Management:**

* List all accessible accounts under a manager (MCC) hierarchy
* Compare performance across client accounts
* Automate cross-account reporting workflows