reporting.search runs a Google Ads Query Language statement and returns rows; reporting.mutate applies operations to any entity; the typed operations cover campaigns, campaign budgets and ad groups.
Two credentials are needed beyond the OAuth token. The developer token comes from the Google Ads API Center in a manager account and identifies the application, so it is stored on the integration as developer_token. When calling a client account through its manager, also store the manager’s customer ID as login_customer_id; the plugin sends it as the login-customer-id header. The OAuth scope is https://www.googleapis.com/auth/adwords, which is the only scope the API accepts.
Things to know before you call:
- A developer token is not optional. Without one, Google answers a
HeaderErroreven when the OAuth token is valid. - Customer IDs are digits. Google rejects a hyphenated ID with
CLIENT_CUSTOMER_ID_INVALID, so the plugin removes the hyphens for you. searchpages at a fixed 10,000 rows. There is nopageSize(Google removed it in v17 and answersPAGE_SIZE_NOT_SUPPORTED). PassnextPageTokenback aspageToken.searchStreamreturns everything in one response, as a JSON array of chunks that the plugin flattens into oneresultslist.- Money is micros, sent as strings.
5000000is 5.00 in the account currency. The plugin keeps Google’s string type so no precision is lost. - An update needs
updateMask. Google ignores an update without one. The plugin makes it required. - Spending operations are
destructive.campaigns.create(a new campaign defaults toENABLED),campaigns.update,adGroups.update,campaignBudgets.updateandreporting.mutatecan start or change spend, so they need approval wherever destructive calls do. Every mutate takesvalidateOnly: trueto check a request without applying it. - New campaigns declare EU political advertising.
campaigns.createrequirescontainsEuPoliticalAdvertising; Google refuses a new campaign without it. - A remove is a status change to
REMOVED. The row stays and its metrics stay readable, but the campaign cannot be brought back; the plugin markscampaigns.removeirreversible. customers.updatetakes a single operation and answers a singleresult. It is the one mutate that is not a batch, and only the tracking fields are writable.- Errors branch on the canonical status first.
429is a quota rejection,403a permission problem,400a bad request. The specific reason is aGoogleAdsFailuredetail, which the plugin keeps on the error body. - No inbound webhooks. The Google Ads API does not send any, so this plugin registers no webhook route.
- 13 typed API operations
Setup
1
Install
2
Add the plugin
corsair.ts
multiTenancy: true, scope calls with corsair.withTenant(id). See Quick start for KEK + Hub keys, and Multi-tenancy for account isolation.3
Choose authentication
- OAuth 2.0 (Recommended)
Open hub.corsair.dev, navigate to your project, and enter the client ID and client secret from your Google Ads OAuth app.More: OAuth 2.0
4
Connect a tenant
Mint a connect link and send the tenant to it. Hub hosts the page and delivers the result to your app — see Connect / OAuth.
Example API calls
Read the enabled campaigns in an accountWhat’s next
API reference
Every
googleads.api.* operation with input and output types.Connect / OAuth
createLink, Hub delivery, and tenant connect flows.
Use with agents
Expose this plugin’s operations as MCP tools.