# Google Ads on boxd

> Google Ads, is an online advertising platform developed by Google, where advertisers bid to display brief advertisements, service offerings, product listings, and videos to web users.

- Page: https://boxd.sh/integrations/googleads/
- CLI: `run googleads` (22 commands, 17 marked common)
- SDK: `import { googleads } from "@boxd/run"`; every parameter and response type is at `@boxd/run/googleads`
- Triggers: none
- Connect: `run auth googleads` (Sign in with Google Ads), or https://app.boxd.sh/integrations/detail/googleads
- All integrations: https://boxd.sh/integrations/ (Markdown: https://boxd.sh/integrations/index.md)

## From the shell

```sh
run auth googleads      # once: prints a link to connect your account
run googleads           # list its commands
run googleads list-sub-accounts
```

Parameters are flags (`--flag value`); object and array parameters take a JSON string. Output is YAML, or JSON with `--json`. Calls use your own connection; `--scope <name>` uses a connection shared with your team.

## From a script

```ts
import { every, googleads } from "@boxd/run";

every("1 hour", async () => {
  const result = await googleads.listSubAccounts({});
  console.log(result);
});
```

Run it with `run googleads.run.ts`. Google Ads has no triggers; `every()` polls on a schedule, keeps the script running as a job, and wakes the machine when it is due.

## Commands

Required flags are listed; `run googleads <command> --help` lists the optional ones. "common" marks what `run googleads` shows without `--all`.

| Command | SDK method | Required flags | Optional | Description |
|---|---|---|---|---|
| `add-or-remove-to-customer-list` | `googleads.addOrRemoveToCustomerList()` | `--emails` `--resource-name` | 2 | Adds or removes contacts from a Google Ads customer list (UserList/audience/remarketing list), not a Google Ads customer account |
| `create-customer-list` | `googleads.createCustomerList()` | `--name` | 2 | Creates a Google Ads customer list (UserList/audience/remarketing list), not a Google Ads customer account |
| `get-campaign-by-id` | `googleads.getCampaignById()` | `--id` | 1 | GetCampaignById Tool returns details of a campaign in Google Ads |
| `get-campaign-by-name` | `googleads.getCampaignByName()` | `--name` | 1 | Queries Google Ads via SQL to retrieve a campaign by its exact name |
| `get-customer-lists` | `googleads.getCustomerLists()` | — | 2 | GetCustomerLists Tool lists all customer lists (audience/remarketing lists) in Google Ads |
| `list-accessible-customers` ·common | `googleads.listAccessibleCustomers()` | — | 1 | List Google Ads customer resource names directly accessible to the authenticated user |
| `list-sub-accounts` ·common | `googleads.listSubAccounts()` | — | 2 | List direct child/sub-accounts under a Google Ads manager (MCC) account |
| `mutate-ad-group-ads` ·common | `googleads.mutateAdGroupAds()` | `--operations` | 4 | Create, update, or remove ads in Google Ads ad groups, including responsive search ads |
| `mutate-ad-group-assets` ·common | `googleads.mutateAdGroupAssets()` | `--operations` | 4 | Create, update, or remove links between assets and ad groups |
| `mutate-ad-group-bid-modifiers` ·common | `googleads.mutateAdGroupBidModifiers()` | `--operations` | 4 | Create, update, or remove ad group bid modifiers, such as device bid adjustments or hotel-specific bid modifier criteria |
| `mutate-ad-group-criteria` ·common | `googleads.mutateAdGroupCriteria()` | `--operations` | 4 | Create, update, or remove criteria attached to a Google Ads ad group in a single batch request |
| `mutate-ad-groups` ·common | `googleads.mutateAdGroups()` | `--operations` | 3 | Create, update, or remove ad groups within Google Ads campaigns |
| `mutate-assets` ·common | `googleads.mutateAssets()` | `--operations` | 4 | Create or update Google Ads assets such as sitelinks, callouts, structured snippets, text assets, lead forms, promotions, calls, price assets, and media assets |
| `mutate-bidding-strategies` ·common | `googleads.mutateBiddingStrategies()` | `--operations` | 4 | Create, update, or remove portfolio bidding strategies such as Target CPA, Target ROAS, Target Spend, Maximize Conversions, Maximize Conversion Value, Target Impression Share, and Enhanced CPC |
| `mutate-campaign-assets` ·common | `googleads.mutateCampaignAssets()` | `--operations` | 4 | Create, update, or remove links between assets and campaigns |
| `mutate-campaign-budgets` ·common | `googleads.mutateCampaignBudgets()` | `--operations` | 4 | Create, update, or remove Google Ads campaign budgets |
| `mutate-campaign-criteria` ·common | `googleads.mutateCampaignCriteria()` | `--operations` | 4 | Create, update, or remove campaign-level targeting criteria such as locations, languages, campaign-level negative keywords, devices, schedules, audiences, and IP exclusions |
| `mutate-campaign-labels` ·common | `googleads.mutateCampaignLabels()` | `--operations` | 3 | Create or remove relationships between campaigns and labels |
| `mutate-campaigns` ·common | `googleads.mutateCampaigns()` | `--operations` | 4 | Create, update, or remove Google Ads campaigns in batch |
| `mutate-conversion-actions` ·common | `googleads.mutateConversionActions()` | `--operations` | 4 | Create, update, or remove Google Ads conversion actions for conversion tracking configuration |
| `mutate-labels` ·common | `googleads.mutateLabels()` | `--operations` | 4 | Create, update, or remove Google Ads labels |
| `search-stream-gaql` ·common | `googleads.searchStreamGaql()` | `--query` | 2 | Execute a Google Ads Query Language (GAQL) query and stream all results in a single response |

## Docs

- [run CLI](https://docs.boxd.sh/cli/run): Call connected integrations from the shell, connect new ones, and run automations.
- [Quickstart](https://docs.boxd.sh/guides/integrations/quickstart): Connect an integration, call it from the shell, and turn a script into an automation.
- [Connections](https://docs.boxd.sh/guides/integrations/connections): Connect an account once, for yourself or for your whole organization.
- [Scripts](https://docs.boxd.sh/guides/automations/scripts): Typed integrations, triggers, schedules and state in a .run.ts file.
- [Jobs](https://docs.boxd.sh/guides/automations/jobs): How a script becomes a background job: states, retries, sleep and wake.
- [Beyond the catalog](https://docs.boxd.sh/guides/automations/beyond-the-catalog): Reach your own APIs, databases and cloud accounts from a script.