> ## Documentation Index
> Fetch the complete documentation index at: https://leverhq.app/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Google Ads Tools

> Actions for managing Google Ads campaigns

# Google Ads Tools

Tools for creating, reading, updating, and optimizing Google Ads campaigns, ad groups, keywords, and ads.

<Note>
  If you have only one Google Ads account connected, the `customerId` parameter is optional — Lever auto-resolves it. If multiple accounts are connected, you must specify the ID. Use [`list_connections`](/tools/cross-platform#list_connections) to find your account IDs.
</Note>

***

## google\_ads\_list\_campaigns

List all campaigns in the connected Google Ads account with performance metrics.

**Type:** read

| Parameter    | Type   | Required | Description            |
| ------------ | ------ | -------- | ---------------------- |
| `customerId` | string | No       | Google Ads customer ID |

**Example prompt:** "Show me all my Google Ads campaigns"

**Returns:** Campaign name, status, daily budget, CPA, and CTR for each campaign.

***

## google\_ads\_get\_campaign

Get details of a specific Google Ads campaign.

**Type:** read

| Parameter    | Type   | Required | Description            |
| ------------ | ------ | -------- | ---------------------- |
| `customerId` | string | No       | Google Ads customer ID |
| `campaignId` | string | Yes      | Campaign ID            |

**Example prompt:** "Get details for Google Ads campaign 12345"

**Returns:** Campaign name, ID, status, budget, impressions, clicks, and CPA.

***

## google\_ads\_query

Execute a raw [GAQL (Google Ads Query Language)](https://developers.google.com/google-ads/api/docs/query/overview) query for advanced reporting. Returns paginated results (default 50 rows) with cursor-based pagination.

**Type:** read

| Parameter    | Type    | Required | Description                                                                                               |
| ------------ | ------- | -------- | --------------------------------------------------------------------------------------------------------- |
| `customerId` | string  | No       | Google Ads customer ID                                                                                    |
| `query`      | string  | Yes      | GAQL query string                                                                                         |
| `limit`      | number  | No       | Maximum rows per page (default: 50, max: 10000). Response includes a cursor for the next page.            |
| `orderBy`    | string  | No       | Sort results, e.g. `metrics.clicks DESC`. Injected as ORDER BY if not already in the query.               |
| `summary`    | boolean | No       | When true, returns aggregated stats (total count, summary metrics, top 10 rows) instead of full row data. |
| `cursor`     | string  | No       | Pagination cursor from a previous response. Pass to fetch the next page.                                  |

<Note>
  Default limit is 50 rows. Pass `limit: 10000` for larger result sets, or use `cursor` for pagination.
  GAQL does not support OFFSET — use cursor-based pagination instead.
  `summary` cannot be combined with `limit` or `cursor`.
</Note>

**Example prompt:** "Run a GAQL query to get campaign performance for the last 30 days"

**Example prompt:** "Get the top 25 search terms by clicks for campaign 12345"
→ Uses `limit: 25, orderBy: "metrics.clicks DESC"`

**Example prompt:** "Give me a summary of all search terms"
→ Uses `summary: true`

### Example GAQL Queries

**Campaign performance:**

```sql theme={null}
SELECT
  campaign.name,
  campaign.status,
  metrics.impressions,
  metrics.clicks,
  metrics.cost_micros,
  metrics.conversions
FROM campaign
WHERE segments.date DURING LAST_30_DAYS
ORDER BY metrics.cost_micros DESC
```

**Ad group metrics:**

```sql theme={null}
SELECT
  ad_group.name,
  ad_group.status,
  metrics.impressions,
  metrics.clicks,
  metrics.average_cpc
FROM ad_group
WHERE campaign.id = 12345
  AND segments.date DURING LAST_7_DAYS
```

**Keyword stats:**

```sql theme={null}
SELECT
  ad_group_criterion.keyword.text,
  ad_group_criterion.keyword.match_type,
  metrics.impressions,
  metrics.clicks,
  metrics.conversions
FROM keyword_view
WHERE segments.date DURING LAST_7_DAYS
ORDER BY metrics.impressions DESC
LIMIT 20
```

**Keywords in an ad group:**

```sql theme={null}
SELECT
  ad_group_criterion.keyword.text,
  ad_group_criterion.keyword.match_type,
  ad_group_criterion.status
FROM ad_group_criterion
WHERE ad_group.id = 12345
  AND ad_group_criterion.type = 'KEYWORD'
```

***

## google\_ads\_update\_campaign

Update a Google Ads campaign's name, status, budget, end date, or targeting. Goes through [draft-preview-confirm](/trust/safety-model) — returns a preview that must be confirmed before the change executes.

**Type:** write (draft-preview-confirm)

| Parameter      | Type                  | Required | Description                                               |
| -------------- | --------------------- | -------- | --------------------------------------------------------- |
| `customerId`   | string                | No       | Google Ads customer ID                                    |
| `campaignId`   | string                | Yes      | Campaign ID                                               |
| `campaignName` | string                | No       | New campaign name                                         |
| `status`       | `ENABLED` \| `PAUSED` | No       | New campaign status                                       |
| `dailyBudget`  | number                | No       | New daily budget in account currency                      |
| `endDate`      | string                | No       | Campaign end date (YYYY-MM-DD)                            |
| `locationIds`  | string\[]             | No       | Geo target constant IDs (replaces all existing locations) |
| `languageIds`  | string\[]             | No       | Language constant IDs (replaces all existing languages)   |

**Example prompt:** "Pause campaign 12345" or "Target the US and Canada for campaign 12345"

<Note>
  At least one field must be provided. Targeting updates replace all existing targets of that type. Common location IDs: `2840` (US), `2124` (Canada), `2826` (UK). Common language IDs: `1000` (English), `1003` (Spanish), `1001` (French).
</Note>

<Note>
  Budget updates on shared budgets (budgets linked to multiple campaigns) are not yet supported.
  Use the Google Ads UI for shared budget changes.
</Note>

**Returns:** A draft preview showing the proposed changes and a `draftId`. Call [`confirm_draft`](/tools/cross-platform#confirm_draft) to execute.

***

## google\_ads\_create\_ad\_group

Create a new ad group with keywords and a responsive search ad in an existing Search campaign. Goes through [draft-preview-confirm](/trust/safety-model).

**Type:** write (draft-preview-confirm)

| Parameter              | Type                           | Required | Description                               |
| ---------------------- | ------------------------------ | -------- | ----------------------------------------- |
| `customerId`           | string                         | No       | Google Ads customer ID                    |
| `campaignId`           | string                         | Yes      | Campaign ID                               |
| `adGroupName`          | string                         | Yes      | Ad group name                             |
| `keywords`             | array                          | Yes      | Keywords (1-20)                           |
| `keywords[].text`      | string                         | Yes      | Keyword text (max 80 chars)               |
| `keywords[].matchType` | `BROAD` \| `PHRASE` \| `EXACT` | No       | Match type (default: BROAD)               |
| `headlines`            | string\[]                      | Yes      | RSA headlines (3-15, max 30 chars each)   |
| `descriptions`         | string\[]                      | Yes      | RSA descriptions (2-4, max 90 chars each) |
| `finalUrl`             | string                         | Yes      | Landing page URL                          |

**Example prompt:** "Create a new ad group 'Running Shoes' in campaign 12345 with keywords 'running shoes' and 'athletic footwear'"

<Note>
  Only Search campaigns are supported. The ad group, keywords, and ad are created atomically — if any part fails, nothing is created.
</Note>

**Returns:** A draft preview showing the ad group, keywords, and ad to be created with a `draftId`. Call [`confirm_draft`](/tools/cross-platform#confirm_draft) to execute.

***

## google\_ads\_update\_ad\_group

Update a Google Ads ad group's name. Goes through [draft-preview-confirm](/trust/safety-model).

**Type:** write (draft-preview-confirm)

| Parameter     | Type   | Required | Description            |
| ------------- | ------ | -------- | ---------------------- |
| `customerId`  | string | No       | Google Ads customer ID |
| `adGroupId`   | string | Yes      | Ad group ID            |
| `adGroupName` | string | Yes      | New ad group name      |

**Example prompt:** "Rename ad group 12345 to 'Brand Keywords'"

**Returns:** A draft preview with a `draftId`. Call [`confirm_draft`](/tools/cross-platform#confirm_draft) to execute.

***

## google\_ads\_manage\_keywords

Add and/or remove keywords in an ad group. Goes through [draft-preview-confirm](/trust/safety-model).

**Type:** write (draft-preview-confirm)

| Parameter         | Type                           | Required | Description                                  |
| ----------------- | ------------------------------ | -------- | -------------------------------------------- |
| `customerId`      | string                         | No       | Google Ads customer ID                       |
| `adGroupId`       | string                         | Yes      | Ad group ID                                  |
| `add`             | array                          | No       | Keywords to add (max 20)                     |
| `add[].text`      | string                         | Yes      | Keyword text (max 80 chars)                  |
| `add[].matchType` | `BROAD` \| `PHRASE` \| `EXACT` | Yes      | Match type                                   |
| `remove`          | string\[]                      | No       | Criterion IDs of keywords to remove (max 20) |

**Example prompt:** "Add 'running shoes' and remove keyword 456 from ad group 123"

<Note>
  At least one of `add` or `remove` must be provided. Additions are processed before removals. Get criterion IDs using `google_ads_query` on `ad_group_criterion`.
</Note>

**Returns:** A draft preview with a `draftId`. Call [`confirm_draft`](/tools/cross-platform#confirm_draft) to execute.

***

## google\_ads\_update\_keyword\_bids

Update CPC bid overrides on keywords in an ad group. Goes through [draft-preview-confirm](/trust/safety-model).

**Type:** write (draft-preview-confirm)

| Parameter                | Type   | Required | Description                     |
| ------------------------ | ------ | -------- | ------------------------------- |
| `customerId`             | string | No       | Google Ads customer ID          |
| `adGroupId`              | string | Yes      | Ad group ID                     |
| `keywords`               | array  | Yes      | Keywords with new bids (max 20) |
| `keywords[].criterionId` | string | Yes      | Keyword criterion ID            |
| `keywords[].cpcBid`      | number | Yes      | New CPC bid in account currency |

**Example prompt:** "Set the CPC bid for keyword 123 in ad group 789 to \$2.50"

**Returns:** A draft preview with a `draftId`. Call [`confirm_draft`](/tools/cross-platform#confirm_draft) to execute.

***

## google\_ads\_update\_ad

Update a Responsive Search Ad's headlines, descriptions, or landing page URL. Goes through [draft-preview-confirm](/trust/safety-model).

**Type:** write (draft-preview-confirm)

| Parameter      | Type      | Required | Description                               |
| -------------- | --------- | -------- | ----------------------------------------- |
| `customerId`   | string    | No       | Google Ads customer ID                    |
| `adGroupId`    | string    | Yes      | Ad group ID containing the ad             |
| `adId`         | string    | Yes      | Ad ID to update                           |
| `headlines`    | string\[] | No       | New headlines (3-15, max 30 chars each)   |
| `descriptions` | string\[] | No       | New descriptions (2-4, max 90 chars each) |
| `finalUrl`     | string    | No       | New landing page URL                      |

**Example prompt:** "Update the headlines on ad 456 in ad group 123"

<Note>
  At least one field must be provided. When updating headlines or descriptions, provide the complete set — they replace all existing values. Only Responsive Search Ads are supported.
</Note>

**Returns:** A draft preview with a `draftId`. Call [`confirm_draft`](/tools/cross-platform#confirm_draft) to execute.