Analytics and ads
Google Ads
Connect one Google Ads account to a workspace so your agent can read reports and create paused campaigns: the tools, what each costs, the daily budget cap, and what each error means.
What does connecting Google Ads do?
Your agent can read the account's reports and campaign structure, create Search campaigns, turn campaigns, ad groups and ads on and off, and change a campaign's daily budget. Google bills ad spend to your Google Ads account.
What keeps an ad from spending by accident?
A new campaign is always paused. No tool can create one that is already on, and none can delete one.
Turning something on and raising a budget need a daily budget cap, which you set on the Connections screen. With no cap, both are refused. Only a person signed in to the dashboard can set it. Write API keys and agents you approved can turn ads on within it.
The cap limits the total daily budget of the campaigns that are on. It is not a limit on what Google spends on a given day. One change can raise a budget to at most twice what it was. Turning things off skips all of these checks.
How do I connect a Google Ads account?
Set up a passkey first
Google asks for a passkey when you connect, and a new one can take up to 7 days to work. Set it up at g.co/passkeys.
Open Connections in a workspace
Pick the workspace first. The account belongs to that workspace.
Press New connection, then Google Ads
It is in the Analytics and ads group, below the channels. Press Connect Google Ads, then allow access on Google's screen.
Pick the account
If only one account can run ads, it connects right away. Manager accounts are not listed, but the accounts under them are.
Set a daily budget cap
Enter it on the card, in the account's currency. Until you do, your agent can read and create paused campaigns but cannot turn anything on.
Which tools does my agent get?
Google limits how many operations uplika can make in a day, shared across everyone on uplika. The last column is what one call uses. An agent connected before this existed has to approve uplika again to use the write tools.
| Tool | What it does | Permission | Operations |
|---|---|---|---|
| get_ad_account | The connected account, its currency, your cap, and the operations left today | posts:read | 0 |
| get_ad_insights | Impressions, clicks, cost, conversions and more, by account, campaign, ad group, ad or keyword, for a period | posts:read | 1 |
| list_ads | Campaigns, ad groups and ads with status and daily budget. It can show only what uplika created | posts:read | 2 |
| create_ad_campaign | One Search campaign, always paused. validateOnly checks it without creating it | ads:write | 4 + keywords + locations |
| set_ad_status | Turn a campaign, ad group or ad on or off | ads:write | 1 to turn off, 2 to turn on |
| update_ad_budget | Change a campaign's daily budget | ads:write | 2 |
What do the errors mean?
| Code | HTTP | What it means and what to do |
|---|---|---|
| integration_not_connected | 404 | This workspace has no Google Ads connection. Connect one on the Connections screen. |
| integration_reconnect_required | 409 | Google ended this connection. Reconnect it on the Connections screen. |
| ad_budget_cap_unset | 409 | No daily budget cap is set. Set one on the Connections screen, then try again. |
| ad_budget_cap_exceeded | 422 | This would take the campaigns that are on above your cap. The reply has the cap and the total. Raise the cap yourself, or lower the budget. |
| ad_budget_increase_too_large | 422 | A budget can at most double in one change. Raise it in steps. |
| ad_budget_unreadable | 422 | Google gave no daily budget for a campaign in this account, so uplika cannot check your cap. Make this change in Google Ads. |
| ad_status_superseded | 409 | A pause for the same ad arrived while turning it on waited in line, so it stays off. Send it again if you still want it on. |
| ads_no_access | 403 | This Google account can no longer open the Google Ads account. Get access back, or reconnect with another account. |
| ads_quota_exhausted | 429 | This workspace, or uplika as a whole, used its Google Ads operations for today. Try again after the time in retryAfter. uplika's count does not block turning an ad off by its id, and list_ads keeps a small reserve to find the id. Google can still refuse at its own limit. In that case turn the ad off in Google Ads. |
| ads_access_level_insufficient | 403 | Google refused because uplika's API access level does not cover this account yet. Tell us at support@uplika.com. |
| ads_two_step_required | 403 | A manager account above this one requires 2-Step Verification. Turn it on for the Google account, then try again. |
| ads_upstream_rejected | 422 | Google refused the request, often on ad policy or validation. googleErrors in the reply has Google's reason. Change the request instead of sending it again. |
| ads_upstream_unavailable | 503 | Google did not answer in time, or kept asking us to slow down. Check with list_ads whether the change happened before you send it again. |
Why did connecting fail?
| What you see | What to do |
|---|---|
| You cancelled on Google's screen. Nothing was connected. | Start again and allow access on Google's screen. |
| uplika needs permission to manage your Google Ads campaigns. Leave that box checked. | Start again and leave the Google Ads box checked. |
| This Google account cannot open a Google Ads account that runs ads. | Use a Google account that can open a Google Ads account that runs ads. A manager account with nothing under it is not enough. |
| A manager account above this one requires 2-Step Verification. Turn it on for this Google account, then connect again. | Turn on 2-Step Verification for this Google account, then start again. |
| Google did not give lasting access. Remove uplika in your Google Account and connect again. | Open your Google Account permissions, remove uplika, then connect again. |
| That connection link expired. Start again. | A connection link lasts up to an hour. Start again from Connections. |
| This connection was started from another uplika account, or you are signed out. Sign in and start again from Connections. | Finish in the browser where you started, signed in to the same uplika account. Do not use a connection link someone sent you. |
| Google did not finish the sign-in. Try again. | Start again from Connections. |
Can I call these tools over REST?
Yes. Each tool calls one of these routes. Reads need posts:read and writes need ads:write, which every write API key has. Send x-uplika-workspace when you have more than one workspace; the account is the one connected to it. Ids are the Google resource names GET /v1/integrations/google_ads/objects returns, URL-encoded in the path (customers%2F1234567890%2Fcampaigns%2F111). The daily budget cap has no route here, because only a person signed in to the dashboard sets it.
GET/v1/integrations/google_ads/account
The connected account, its daily budget cap and today's allowance. Calls no Google. Same as get_ad_account.
POST/v1/integrations/google_ads/insights
Metrics at one level, money in the account currency. Same as get_ad_insights.
| Name | Type | Description |
|---|---|---|
level | string | account, campaign, ad_group, ad or keyword. Defaults to campaign. |
range | string | A Google date range such as LAST_7_DAYS. Defaults to LAST_30_DAYS. Use this or startDate with endDate. A wrong one comes back as invalid_params with the allowed list. |
startDate | string | YYYY-MM-DD. Needs endDate. |
endDate | string | YYYY-MM-DD. Needs startDate. |
metrics | string[] | Defaults to all of them. An unknown name comes back as invalid_params with the allowed list. |
limit | number | Rows to return. |
GET/v1/integrations/google_ads/objects
Campaigns, ad groups and ads as a tree, with ids, statuses and daily budgets. Same as list_ads.
Can I list only what uplika made?
| Name | Type | Description |
|---|---|---|
createdByUplika | query | true lists only campaigns created through uplika. |
POST/v1/integrations/google_ads/campaigns
Create one Search campaign, always paused. Same as create_ad_campaign.
| Name | Type | Description |
|---|---|---|
nameRequired | string | Campaign name. Unique in the account. |
dailyBudgetRequired | number | Per day, in the account currency, not micros. |
countriesRequired | string[] | ISO country codes such as KR. |
euPoliticalAdvertisingRequired | boolean | Whether the campaign contains EU political advertising. The advertiser's own declaration, so it has no default. |
keywordsRequired | object[] | [{ text, matchType }]. matchType is EXACT, PHRASE or BROAD. |
finalUrlsRequired | string[] | The landing page, https. |
headlinesRequired | string[] | Responsive search ad headlines. Full-width characters such as Hangul count as 2. |
descriptionsRequired | string[] | Responsive search ad descriptions. Full-width characters such as Hangul count as 2. |
maxCpc | number | Highest cost per click, in the account currency. Bidding is maximize clicks. |
adGroupName | string | Defaults to the campaign name with -ag. |
path1 | string | First display URL path. |
path2 | string | Second display URL path. |
validateOnly | boolean | Google checks everything and nothing is created. |
Idempotency-Key | header | Send the same key when you retry and we return the first answer instead of making the change twice. |
POST/v1/integrations/google_ads/objects/{id}/status
Turn a campaign, ad group or ad on or off. Same as set_ad_status.
| Name | Type | Description |
|---|---|---|
statusRequired | string | ENABLED or PAUSED. ENABLED goes through only inside the daily budget cap. PAUSED is never blocked by the cap or by uplika's allowance. |
Idempotency-Key | header | Send the same key when you retry and we return the first answer instead of making the change twice. |
POST/v1/integrations/google_ads/objects/{id}/budget
Change a campaign's daily budget. Same as update_ad_budget.
| Name | Type | Description |
|---|---|---|
dailyBudgetRequired | number | New amount per day, in the account currency, not micros. The id must be a campaign. A shared budget changes for every campaign using it. |
Idempotency-Key | header | Send the same key when you retry and we return the first answer instead of making the change twice. |
What does uplika store?
To keep the connection: the encrypted tokens, the account's id and name, its currency and time zone, whether it is a test account, the manager account it is reached through, your cap, and your Google account id.
A record of what uplika created or changed: each object's name, status and daily budget, and each change with its before and after values. Metrics are never written to our database.
What happens when I disconnect?
Your ads do not stop. Ads that are on keep running in Google and keep spending, so turn them off first, through your agent or in Google Ads. uplika deletes the stored tokens and asks Google to end its access, unless the same Google account is still connected elsewhere in uplika. The record of what uplika created or changed stays until you delete the workspace or your account.
Frequently asked
Can my agent turn on an ad by itself?
Only within a daily budget cap you set on the Connections screen. With no cap, it can read and create paused campaigns, and nothing more.
Does disconnecting stop my ads?
No. Ads that are on keep running in Google until you turn them off, through your agent or in Google Ads.
Can I connect more than one account?
One per workspace. To work in another account, connect it in another workspace.