Google Ads

Google Ads Customers API

Access and manage Google Ads customer account information

GitHub OpenAPI
Business capability
Digital Marketing Management BC-400.60

Operations 33

Each operation below carries the questions people ask an LLM about it and the instructions they give an agent to run it. Generated by API Evangelist overlay

GET /v18/customers/{customerId} Get a Google Ads account's details · Google Ads Get Customer Account Details #
Ask an LLM
“What details can I pull back about a single Google Ads account through the v18 API?”
“Can I tell whether an account is a manager account or a regular client account?”
Tell an agent
Get the full account details for Google Ads customer {customer} using the v18 endpoint.
Show me the v18 account record for {customer}, including whether it is a manager account.
GET /v18/customers:listAccessibleCustomers List accounts my login can access (v18) · Google Ads List Accessible Customer Accounts #
Ask an LLM
“Which Google Ads accounts can my OAuth login reach directly on the v18 API?”
“Is there a way to find my customer IDs without already knowing one?”
Tell an agent
Using developer token {devtoken}, list every account my credentials can access on v18.
Find the v18 customer resource names I can reach with developer token {devtoken}.
POST /v25/customers/{customersId}:generateShareablePreviews Generate shareable ad previews · Returns the requested Shareable Preview #
Ask an LLM
“Can I produce a preview link of my ads to share with a client who has no account access?”
“What does a shareable preview for an asset group look like before it goes live?”
Tell an agent
Generate shareable previews for account {customer}.
Create a shareable preview link in account {customer} using preview request {operation}.
GET /v25/customers:listAccessibleCustomers List accounts my login can access (v25) · Returns resource names of customers directly accessible by the user… #
Ask an LLM
“Which customer accounts does my authenticated user reach directly on the current v25 API?”
“What comes back from the v25 accessible-customers call when I have several accounts?”
Tell an agent
List the customer resource names my current credentials can access on v25.
Show all accounts directly accessible to the user I authenticated as, via v25.
POST /v25/customers/{customersId}:generateKeywordHistoricalMetrics Get historical metrics for keywords · Returns a list of keyword historical metrics #
Ask an LLM
“How many monthly searches did a set of keywords get historically?”
“Can I see past search volume and competition for keywords in one language and location?”
Tell an agent
Get historical search metrics for keywords {keywords} in account {customer}.
Pull historical volume for {keywords} in language {language} for account {customer}.
POST /v25/customers/{customersId}:suggestKeywordThemes Suggest keyword themes for a Smart campaign · Suggests keyword themes to advertise on #
Ask an LLM
“What keyword themes would suit my business for a Smart campaign?”
“Can I get keyword theme suggestions based on my business details?”
Tell an agent
Suggest keyword themes to advertise on for account {customer}.
Suggest keyword themes for account {customer} from business info {info}.
POST /v25/customers/{customersId}:generateAudienceDefinition Turn a text description into an audience · Returns a collection of audience attributes using generative AI based on the… #
Ask an LLM
“Can I describe my ideal audience in plain words and get targetable attributes back?”
“Which audience attributes does generative AI suggest for a written audience description?”
Tell an agent
Generate audience attributes for account {customer} from the description {description}.
Use AI to build an audience definition in account {customer} for {description}.
POST /v25/customers/{customersId}:generateTrendingInsights Get trending YouTube content insights · Returns insights for trending content on YouTube #
Ask an LLM
“What content is trending on YouTube for my audience in a given country?”
“Can I see trending YouTube topics filtered to specific search topics?”
Tell an agent
Show trending YouTube content insights for account {customer} in country {country}.
Get trending insights for account {customer} around topics {topics}.
POST /v25/customers/{customersId}:generateAudienceOverlapInsights Estimate audience overlap on YouTube · Returns a collection of audience attributes along with estimates of the overlap… #
Ask an LLM
“How much does one audience attribute's YouTube reach overlap with others?”
“Which attributes share the most potential reach with my primary audience?”
Tell an agent
Estimate YouTube reach overlap with attribute {primary} for account {customer} in {country}.
Compare audience overlap for primary attribute {primary} in account {customer}.
POST /v25/customers/{customersId}:suggestSmartCampaignBudgetOptions Suggest budgets for a Smart campaign · Returns BudgetOption suggestions #
Ask an LLM
“What daily budget options are recommended for a Smart campaign?”
“Can I get budget suggestions for an existing Smart campaign rather than a new one?”
Tell an agent
Suggest Smart campaign budget options for account {customer}.
Get budget option suggestions for Smart campaign {campaign} in account {customer}.
POST /v25/customers/{customersId}:generateSuggestedTargetingInsights Suggest audiences relevant to my audience · Returns a collection of targeting insights (e.g #
Ask an LLM
“Which targetable audiences are relevant to the audience I care about?”
“Can I get targeting suggestions from a free-text audience description?”
Tell an agent
Suggest targeting insights for account {customer} based on audience {audience}.
Find targetable audiences in account {customer} matching the description {description}.
POST /v25/customers/{customersId}:generateKeywordForecastMetrics Forecast clicks and cost for a keyword plan · Returns metrics (such as impressions, clicks, total cost) of a keyword forecast… #
Ask an LLM
“What impressions, clicks and cost should I expect from a planned campaign's keywords?”
“Can I forecast keyword performance over a specific future period and currency?”
Tell an agent
Forecast keyword metrics for campaign {campaign} in account {customer}.
Forecast impressions and cost for {campaign} over period {period} in account {customer}.
POST /v25/customers/{customersId}:generateCreatorInsights Get insights on YouTube creators · Returns insights for a collection of YouTube Creators and Channels #
Ask an LLM
“Which YouTube creators and channels reach audiences in my target countries?”
“Can I look up insights for specific YouTube channels I already have in mind?”
Tell an agent
Get creator insights for channels {channels} in account {customer}.
Find YouTube creators on topics {topics} in countries {countries} for account {customer}.
POST /v25/customers/{customersId}:uploadClickConversions Upload offline click conversions · Processes the given click conversions #
Ask an LLM
“How do I send offline sales tied to ad clicks back to my account?”
“Can a click conversion upload accept some rows even when others fail?”
Tell an agent
Upload click conversions {conversions} to account {customer}.
Validate click conversions {conversions} for account {customer} without saving them.
POST /v25/customers/{customersId}:suggestTravelAssets Suggest travel assets for hotels · Returns Travel Asset suggestions #
Ask an LLM
“Can I get ad asset suggestions for a hotel property from its place ID?”
“Which travel assets are suggested for my hotels, and is every asset type guaranteed?”
Tell an agent
Suggest travel assets for place IDs {places} in account {customer}.
Get hotel asset suggestions in language {language} for {places} in account {customer}.
POST /v25/customers/{customersId}:uploadUserData Upload user data to a Customer Match list · Uploads the given user data #
Ask an LLM
“What's the direct way to add hashed contact data to a Customer Match list?”
“Can I push user data straight into a list without creating an offline job first?”
Tell an agent
Upload user data operations {operations} to account {customer}.
Add these customers {operations} to the Customer Match list {metadata} in account {customer}.
POST /v25/customers/{customersId}:uploadConversionAdjustments Adjust or retract reported conversions · Processes the given conversion adjustments #
Ask an LLM
“Can I restate the value of a conversion that was already reported?”
“How do I retract conversions for orders that were later refunded?”
Tell an agent
Upload conversion adjustments {adjustments} to account {customer}.
Retract or restate conversions {adjustments} in account {customer}, allowing partial failure.
POST /v25/customers/{customersId}:removeCampaignAutomaticallyCreatedAsset Remove auto-created assets from a campaign · Removes automatically created assets from a campaign #
Ask an LLM
“Can I get rid of assets Google created automatically at the campaign level?”
“What happens to campaign assets I didn't write myself if I remove them?”
Tell an agent destructive · confirm first
Remove the automatically created campaign assets {operations} in account {customer}.
Strip auto-generated assets from campaigns in account {customer}.
POST /v25/customers/{customersId}:generateAudienceCompositionInsights Compare an audience's makeup to a baseline · Returns a collection of attributes that are represented in an audience of… #
Ask an LLM
“What attributes over-index in my audience compared with a baseline audience?”
“Can I see audience composition for a particular data month?”
Tell an agent
Generate audience composition insights for audience {audience} in account {customer}.
Compare audience {audience} against baseline {baseline} for account {customer}.
POST /v25/customers/{customersId}:suggestSmartCampaignAd Suggest a Smart campaign ad · Suggests a Smart campaign ad compatible with the Ad family of resources, based… #
Ask an LLM
“Can Google write a Smart campaign ad for me from my business details?”
“What ad text is suggested for a Smart campaign based on targeting and business info?”
Tell an agent
Suggest a Smart campaign ad for account {customer}.
Draft a Smart campaign ad in account {customer} using business info {info}.
POST /v25/customers/{customersId}:startIdentityVerification Start advertiser identity verification · Starts Identity Verification for a given verification program type #
Ask an LLM
“How do I kick off advertiser identity verification for my account?”
“Which verification program can I start through the API?”
Tell an agent
Start identity verification for account {customer}.
Begin verification program {program} for account {customer}.
POST /v25/customers/{customersId}:generateReachForecast Forecast reach for a YouTube media plan · Generates a reach forecast for a given targeting / product mix #
Ask an LLM
“How many people could a planned YouTube product mix reach for my budget?”
“Can I forecast reach with a frequency cap and a set campaign duration?”
Tell an agent
Generate a reach forecast for account {customer} with planned products {products}.
Forecast reach for {products} over {duration} in currency {currency} for account {customer}.
GET /v25/customers/{customersId}/getIdentityVerification Check identity verification status · Returns Identity Verification information #
Ask an LLM
“Has my account finished advertiser identity verification yet?”
“Where can I see the current verification status and deadlines for an account?”
Tell an agent
Get the identity verification status for account {customer}.
Check whether account {customer} still needs to verify its identity.
POST /v25/customers/{customersId}:suggestBrands Look up brands by name prefix · Rpc to return a list of matching brands based on a prefix for this customer #
Ask an LLM
“Can I search for a brand by typing the first few letters of its name?”
“Which brands match a prefix, excluding ones I've already selected?”
Tell an agent
Suggest brands starting with {prefix} for account {customer}.
Find matching brands for {prefix} in account {customer}, skipping {selected}.
POST /v25/customers/{customersId}:mutate Update an account's settings · Updates a customer #
Ask an LLM
“Can I change settings on an existing customer account, like its tracking template?”
“Is there a way to check an account update is valid without applying it?”
Tell an agent
Update account {customer} with change {operation}.
Validate the account settings change {operation} on {customer} without applying it.
POST /v25/customers/{customersId}:generateKeywordIdeas Generate new keyword ideas · Returns a list of keyword ideas #
Ask an LLM
“What new keywords should I target based on a seed keyword or my website URL?”
“Can I get keyword ideas for a specific language and set of locations?”
Tell an agent
Generate keyword ideas for account {customer} from seed {seed}.
Suggest keywords from the page {url} for account {customer}.
POST /v25/customers/{customersId}:generateInsightsFinderReport Save an Insights Finder report · Creates a saved report that can be viewed in the Insights Finder tool #
Ask an LLM
“Can I create a saved report to open later in the Insights Finder tool?”
“How can I share an audience comparison as an Insights Finder report?”
Tell an agent
Create an Insights Finder report for audience {audience} in account {customer}.
Save an Insights Finder report comparing {audience} to {baseline} for account {customer}.
POST /v25/customers/{customersId}:uploadCallConversions Upload phone call conversions · Processes the given call conversions #
Ask an LLM
“Can I report conversions that happened over the phone from my ads?”
“What happens if some rows in a call conversion upload are invalid?”
Tell an agent
Upload call conversions {conversions} to account {customer}.
Validate call conversions {conversions} for account {customer} without recording them.
POST /v25/customers/{customersId}:generateAdGroupThemes Suggest ad groups for a set of keywords · Returns a list of suggested AdGroups and suggested modifications (text, match… #
Ask an LLM
“Which of my ad groups should each new keyword go into?”
“Can I get suggested match types and text tweaks when grouping keywords?”
Tell an agent
Suggest ad group themes for keywords {keywords} in account {customer}.
Match keywords {keywords} to ad groups {adgroups} in account {customer}.
POST /v25/customers/{customersId}:createCustomerClient Create a client account under a manager · Creates a new client under manager #
Ask an LLM
“How do I open a new client account under my manager account?”
“Can I invite a user by email with an access role when creating a client account?”
Tell an agent
Create a new client account {client} under manager {customer}.
Create client {client} under manager {customer} and invite {email} as {role}.
POST /v25/customers/{customersId}:generateBenchmarksMetrics Benchmark YouTube ad metrics vs industry · Returns YouTube advertisement metrics for the given client against industry… #
Ask an LLM
“How do my YouTube ad metrics compare with industry benchmarks?”
“Can I benchmark against a specific location and date range?”
Tell an agent
Benchmark YouTube ad metrics for account {customer} over {range}.
Compare account {customer} to benchmarks source {source} in location {location}.
POST /v25/customers/{customersId}:searchAudienceInsightsAttributes Search audience attributes for insights · Searches for audience attributes that can be used to generate insights #
Ask an LLM
“Which audience attributes can I use when generating audience insights?”
“Can I search attributes by free text and limit them to certain countries?”
Tell an agent
Search audience insight attributes matching {text} in account {customer}.
Find audience attributes for {text} across dimensions {dimensions} in account {customer}.
POST /v25/customers/{customersId}:generateTargetingSuggestionMetrics Estimate reach for targetable audiences · Returns potential reach metrics for targetable audiences #
Ask an LLM
“How many men aged 18+ interested in camping can I reach on YouTube?”
“What potential reach do my candidate audiences have?”
Tell an agent
Estimate potential reach for audiences {audiences} in account {customer}.
Get targeting suggestion metrics for account {customer}.

Documentation

📖
Documentation
https://developers.google.com/google-ads/api/docs/start
📖
Authentication
https://developers.google.com/google-ads/api/docs/oauth/overview
📖
RateLimits
https://developers.google.com/google-ads/api/docs/rate-limits
📖
GettingStarted
https://developers.google.com/google-ads/api/docs/first-call/overview

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/google-ads/refs/heads/main/openapi/google-ads-customers-api-openapi.yml

Other Resources

🔗
SDKs
https://developers.google.com/google-ads/api/docs/client-libs
🔗
Migration Guide
https://developers.google.com/google-ads/api/docs/migration
🔗
Best Practices
https://developers.google.com/google-ads/api/docs/best-practices
🔗
ReleaseNotes
https://developers.google.com/google-ads/api/docs/release-notes
🔗
Support
https://developers.google.com/google-ads/api/support
🔗
Forums
https://groups.google.com/g/adwords-api
🔗
Client Libraries
https://developers.google.com/google-ads/api/docs/client-libs
🔗
ChangeLog
https://developers.google.com/google-ads/api/docs/release-notes

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API 
curl "https://apis.io/api/v1/apis/google-ads:google-ads-customers-api"
All apis 
curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

google-ads-customers-api-openapi.yml Raw ↑ 
openapi: 3.2.0
info:
  title: Google Ads Customers API
  x-refined-note:
  - x-discovery-revision differs across the merged source definitions and was not carried
  version: '1.0'
  description: 'Operations tagged Customers across 2 of this provider''s published API definitions: google-ads-api-openapi.yml, google-ads-api-v25-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://googleads.googleapis.com
  description: Google Ads API Production Server
tags:


# --- truncated at 32 KB (400 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/google-ads/refs/heads/main/openapi/google-ads-customers-api-openapi.yml