Technical documentation

Google Ads API — use case and technical documentation

How iGrillo Mídias, a Brazilian paid-media agency, uses the Google Ads API to operate the advertising accounts of its contracted clients.

iGrillo Mídias CNPJ 33.703.618/0001-77 Ribeirão Preto, SP — Brazil Manager account (MCC) 933-713-3172

This page is the English version of the Google Ads API section of our website. The rest of the site is written in Brazilian Portuguese because our clients are Brazilian businesses. Portuguese version: igorgrillo.com.br/google-ads-automation.

1. Business model

iGrillo Mídias is a paid-media agency. Clients sign a management contract that authorizes us to operate their Google Ads accounts on their behalf, and each account is linked to our manager account (MCC) by the client's own authorization.

Our only source of revenue is the management fee paid by those contracted clients. We do not resell API access, we do not sell or syndicate advertising data, and the software described here is not sold, licensed or distributed to third parties.

2. What we are building

Grillo Ads Platform is our internal operations platform. It serves two purposes:

Reporting — collect daily performance data from the accounts we manage and present it in dashboards and periodic reports, so our team and each client work from the same numbers.
Assisted campaign management — allow our media team to perform routine campaign operations from a single interface, instead of repeating the same work account by account in the Google Ads UI.

The reporting half is live today and runs entirely on read-only access. The campaign-management half is what requires Basic Access, since it depends on mutate calls.

3. Who has access

Internal users only. The platform is used exclusively by employees of iGrillo Mídias. There is no client-facing login, no self-service sign-up and no public access of any kind. No contractors, outsourcing partners or third parties have accounts.

User type	Who	What they can do
Internal — Admin	Agency owner	Full access to every managed account: data collection, reporting and campaign operations
Internal — Operator	In-house media team	Run data collection and perform campaign operations on the accounts assigned to them

Our clients never authenticate into the platform and never interact with the Google Ads API through it. What they receive is the outcome of our work: performance reports produced and delivered by our team, and the campaigns running in their own Google Ads accounts, which they own and can always inspect directly in the Google Ads interface.

Authorization is enforced server-side by role, combined with an explicit account-to-user mapping. Authentication uses password login with optional TOTP two-factor, and every access to client data is written to an audit log.

4. Architecture

Layer	Implementation
Application	Next.js (TypeScript), server-side rendering, role-gated routes
Data store	PostgreSQL 16 — one row per account per day, and one row per keyword per day
Collector	TypeScript service calling the Google Ads API REST endpoint `googleAds:search`, scheduled once daily and on manual refresh
Hosting	Dedicated cloud virtual machine, containerized, TLS via Let's Encrypt
Credentials	OAuth2 refresh token and developer token stored as server-side environment variables — never exposed to the browser or to client users

5. How we use the API today (read-only)

All reads go through a single function that issues one googleAds:search request per account per report.

Resource	Purpose
`customer`	Daily account totals: clicks, impressions, CTR, conversions, cost
`keyword_view`	Per-keyword performance, stored daily for trend analysis
`account_budget`	Prepaid balance monitoring, to alert the team before an account runs dry
`customer_client`	Enumerate the accounts linked to the manager account

A representative query:

SELECT segments.date, metrics.clicks, metrics.impressions, metrics.ctr,
       metrics.conversions, metrics.cost_micros
FROM customer
WHERE segments.date BETWEEN '2026-07-25' AND '2026-07-31'

Request volume is small and bounded: a handful of requests per managed account per day, executed in a single scheduled batch, plus occasional on-demand refreshes triggered by an operator. Results are cached in PostgreSQL, so the dashboard never queries the API on page load.

6. What we are requesting Basic Access for (write)

Create campaigns, ad groups and responsive search ads
Pause and enable campaigns, ad groups and ads
Set campaign budgets and bidding strategy targets (target CPA, target ROAS, max CPC)
Add and remove keywords and negative keywords

Human in the loop. Every write operation is initiated by an authenticated internal operator and confirmed in the interface before it is sent. There is no autonomous agent mutating accounts on its own, no unattended bulk automation, and no scheduled job holding write permission.

7. Policy compliance

Scope — the developer token is used only against accounts linked to our own manager account under a signed management contract. We do not access third-party accounts.
No redistribution — API data is never sold, syndicated or exposed through a public API. It is used solely to operate and report on the accounts we manage under contract, and reporting delivered to a client covers only that client's own account.
Rate limits — collection runs as one scheduled daily batch per account, sequentially, well within Basic Access operation limits. Failures are retried with backoff, never in a loop.
Data retention — aggregated performance metrics only. We do not collect or store end-user personal data through the API.
Versioning — the integration targets a current API version and is upgraded ahead of each sunset date. We migrated from v21 to v24 in advance of the 5 August 2026 shutdown.
Security — credentials live only in server-side environment variables on infrastructure we control, with role-based authorization and access logging.

8. Contact

iGrillo Mídias — paid-media agency, registered in Brazil under CNPJ 33.703.618/0001-77, based in Ribeirão Preto, São Paulo, Brazil.

API contact e-mail: contato@igorgrillo.com.br
Company website: igorgrillo.com.br
Manager account (MCC): 933-713-3172

Our privacy policy and terms of use, including the Limited Use disclosure required by the Google API Services User Data Policy, are published at igorgrillo.com.br/privacy and igorgrillo.com.br/terms.