Google Ads

Access the Google Ads API with managed OAuth authentication. Query campaigns, ad groups, keywords, and performance metrics using GAQL.

Reference

List Accessible Customers

GET /google-ads/v24/customers:listAccessibleCustomers

maton google-ads account list

Search (GAQL Query)

POST /google-ads/v24/customers/{customerId}/googleAds:search
Content-Type: application/json

{
  "query": "SELECT campaign.id, campaign.name, campaign.status FROM campaign ORDER BY campaign.id"
}

maton google-ads query -c 1234567890 --resource campaign --fields 'campaign.id, campaign.name, campaign.status' --order-by 'campaign.id'

List Keywords

POST /google-ads/v24/customers/{customerId}/googleAds:search
Content-Type: application/json

{
  "query": "SELECT ad_group_criterion.keyword.text, ad_group_criterion.keyword.match_type, ad_group_criterion.status, metrics.impressions, metrics.clicks, metrics.cost_micros FROM keyword_view WHERE segments.date DURING LAST_30_DAYS ORDER BY metrics.impressions DESC"
}

maton google-ads keyword list -c 1234567890 --date-range LAST_7_DAYS -L 25 --campaign-id 99999

Note: This command requests metrics, so it cannot be run against a manager (MCC) account directly. Run it against the client customer ID under the manager, optionally with --login-customer-id. See Manager (MCC) Account Access.

Search Stream (for large results)

POST /google-ads/v24/customers/{customerId}/googleAds:searchStream
Content-Type: application/json

{
  "query": "SELECT campaign.id, campaign.name FROM campaign"
}

maton google-ads query-stream -c 1234567890 --resource campaign --fields 'campaign.id, campaign.name'

Manager (MCC) Account Access

To reach a client account through a Google Ads manager (MCC) account, put the client's customer ID in the path and pass the manager's customer ID in the login-customer-id header (--login-customer-id in the CLI). Without it, or with a manager that doesn't manage the client, Google returns 403 USER_PERMISSION_DENIED. listAccessibleCustomers lists only the accounts the connection can access directly, not the clients under a manager.

POST /google-ads/v24/customers/1234567890/googleAds:search
Content-Type: application/json
login-customer-id: 9876543210

{
  "query": "SELECT campaign.id, campaign.name FROM campaign"
}

maton google-ads campaign list -c 1234567890 --login-customer-id 9876543210

Notes:

Customer IDs are 10-digit numbers. Remove the dashes from the XXX-XXX-XXXX form shown in the Google Ads UI, in the path and in login-customer-id.

Daily Quota

Maton enforces a daily quota of 1,000 requests per account. The window is 24 hours and starts with your first request; responses report what is left in the RateLimit header. See Daily quotas for details. To increase this limit, reach out to support@maton.ai.