# Google Ads

> Client and manager accounts under one consent, read-only, with campaigns, search terms and conversions next to your Amazon numbers.

Status: Live

- Google Ads: Reads: yes · Writes: no

Every campaign, search term and conversion, next to your Amazon numbers, under the same field names. Build holds the developer token, so you never apply to Google.

## Account types

| Account | Who it is for | What you grant |
|---|---|---|
| Client account | Anyone running ads in their own Google Ads account | Sign in with Google and approve view-only access |
| Manager account (MCC) | Agencies and brands with several accounts | One approval on the manager covers every client under it |

## Connect Google Ads

A few minutes.

1. **Sign in with Google**

   Approve view-only access. For a manager account, one approval covers every client under it.
2. **Pick your accounts**

   Choose the client accounts Build should read.
3. **First data lands**

   It takes minutes. Every row carries its as-of time.

_To write: screenshots of the three console screens, and the exact permission the Google consent screen shows_

## Data you get

Every row says what it is. Some Google data is hidden or restated, and the status says which.

**Campaigns**

| Data | Status | Freshness | History |
|---|---|---|---|
| Spend, clicks, conversions by campaign | Live | hourly | Kept from day one |
| Budgets and bidding strategies | Live | daily | Every change kept |
| Auction insights (competitor share) | Not available | — | Google doesn’t share it |

**Ad groups and ads**

| Data | Status | Freshness | History |
|---|---|---|---|
| Ad group results | Live | hourly | Kept from day one |
| Ads, headlines and their results | Live | hourly | Kept from day one |

**Keywords and search terms**

| Data | Status | Freshness | History |
|---|---|---|---|
| Keywords and Quality Score | Live | daily | Kept from day one |
| Search terms Google shows | Live | daily | Kept from day one |
| Low-volume search terms | Hidden by Google | — | Spend gap shown |
| Who searched (person-level data) | Not available | — | Google doesn’t share it |

**Shopping and Performance Max products**

| Data | Status | Freshness | History |
|---|---|---|---|
| Shopping results by product | Live | daily | Kept from day one |
| Performance Max results by product | Live | daily | Kept from day one |
| Performance Max search terms | Hidden by Google | — | Categories only |

**Conversions**

| Data | Status | Freshness | History |
|---|---|---|---|
| Conversions and value by day | Live | hourly | Every restated value kept |
| Conversions by action | Live | daily | Every restated value kept |

**Geo and device**

| Data | Status | Freshness | History |
|---|---|---|---|
| Results by country, region and city | Live | daily | Kept from day one |
| Results by device and hour of day | Live | daily | Kept from day one |

## Read tools

POST https://build-api.sellermate.ai/v1/tools/get_campaign_performance — Spend, clicks, orders, sales and ACoS for each campaign, in the same fields as Amazon. (writes: no; platforms: Amazon, Google Ads)

POST https://build-api.sellermate.ai/v1/tools/get_search_term_performance — Search terms with their performance, hidden terms marked. (writes: no; platforms: Amazon, Google Ads)

_To write: which data groups in the table each read tool returns, and any Google Ads read tool still to add to the API reference (conversions, geo and device, Shopping and Performance Max)_

## Write tools and guardrails

> **Read-only for now**
>
> Build never changes your Google Ads account. Writes come later. Amazon is the only platform with writes today.

| Google Ads | Today |
|---|---|
| Read campaigns and budgets | Yes |
| Read search terms and conversions | Yes |
| Change bids or budgets | No |
| Pause campaigns or add negatives | No |

## Derived metrics

_To write: the derived metrics on Google Ads (ACoS and TACoS blended with Amazon, brand and non-brand split, conversion lag) with the formula and the inputs of each_

## Freshness

> **Freshness figures (to confirm)**
>
> The figures below are the current site statements. Each is (to confirm) before launch. Past days are re-pulled when Google restates them. Every answer carries `data_as_of`.

| Data | Freshness | History | Status |
|---|---|---|---|
| Spend, clicks, conversions by campaign | hourly | Kept from day one | Live |
| Budgets and bidding strategies | daily | Every change kept | Live |
| Auction insights (competitor share) | — | Google doesn’t share it | Not available |
| Ad group results | hourly | Kept from day one | Live |
| Ads, headlines and their results | hourly | Kept from day one | Live |
| Keywords and Quality Score | daily | Kept from day one | Live |
| Search terms Google shows | daily | Kept from day one | Live |
| Low-volume search terms | — | Spend gap shown | Hidden by Google |
| Who searched (person-level data) | — | Google doesn’t share it | Not available |
| Shopping results by product | daily | Kept from day one | Live |
| Performance Max results by product | daily | Kept from day one | Live |
| Performance Max search terms | — | Categories only | Hidden by Google |
| Conversions and value by day | hourly | Every restated value kept | Live |
| Conversions by action | daily | Every restated value kept | Live |
| Results by country, region and city | daily | Kept from day one | Live |
| Results by device and hour of day | daily | Kept from day one | Live |

## Limits and caveats

| Google's limit | What Build does |
|---|---|
| API access comes in tiers, and approval takes days. | Build already holds the token. You never apply. |
| The search-term report hides low-volume terms. | They show as hidden by Google, with the spend behind them. |
| Conversions arrive late. Past days get restated. | Build re-pulls and shows the restated value. |
| Manager accounts must be linked to their clients. | One consent on the manager covers every client under it. |

What is not available: auction insights and person-level data. Performance Max search terms come as categories only. When you disconnect, Build stops reading right away, and history Build already kept stays yours to delete.

## Five example calls

### 1. Last week's campaigns

**curl**

```bash
curl -X POST https://build-api.sellermate.ai/v1/tools/get_campaign_performance \
  -H "X-API-Key: $BUILD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"account":"gads_northwind","start":"2026-10-22","end":"2026-10-28"}'
```

### 2. Search terms that spend

**curl**

```bash
curl -X POST https://build-api.sellermate.ai/v1/tools/get_search_term_performance \
  -H "X-API-Key: $BUILD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"account":"gads_northwind","start":"2026-10-01","end":"2026-10-28"}'
```

### 3. Amazon and Google Ads side by side

_To write: two get_campaign_performance calls, one per platform, and how to join the rows on the shared field names_

### 4. Hidden search terms

_To write: how a hidden-by-Google term appears in a get_search_term_performance row, with a real sample_

### 5. A restated day

_To write: a call over a range that includes restated conversions, and how data_as_of and the restated value show_

## What the official connectors can't do

_To write: what Google's own tools cannot do that Build does: the same field names as Amazon in one call, one consent for a manager, hidden terms marked with their spend, and history. Compare plainly_

## Changelog

Changes to Google Ads on Build are listed in the [changelog](https://build.sellermate.ai/docs/changelog.md).