Google Ads

Google Ads API access for managing and reporting on Google search, display, and video advertising on behalf of a connected advertiser, query campaigns, ad groups, keywords, and performance via GAQL (googleAds:search), and create or update campaigns, budgets, and ads via :mutate. Use when an agent needs to launch, optimize, or report on Google Ads campaigns. Routes through Pipedream Connect, the user sees one Google consent screen on connect that says “Pipedream wants access” (Pipedream owns the verified OAuth client and the Google Ads developer token), so Lava needs no developer token or API approval of its own. Ad spend is billed by Google directly to the connected account. 4 example endpoints available through Lava’s AI Gateway. See the Google Ads API docs for full documentation.

This provider requires your own credentials — connect your API key or OAuth account before use.

This is a catch-all provider — any valid URL under https://googleads.googleapis.com is supported. Google Ads REST API endpoints. Construct URLs as https://googleads.googleapis.com/v{N}/{path}, where v{N} is the current Google Ads API version (e.g. v21). Every call is POST: read with customers/{customerId}/googleAds:search (a GAQL query in the body, e.g. { “query”: “SELECT campaign.id, campaign.name, metrics.clicks FROM campaign” }) or :searchStream, and write with the :mutate endpoints (campaigns:mutate, adGroups:mutate, adGroupAds:mutate, campaignBudgets:mutate, etc.). customerId is the 10-digit Google Ads account id, in the path as customers/{customerId}/. A real customer id you pass is always used as-is and never redirected (dashes are fine, customers/123-456-7890/… is normalized to digits automatically). If you do not know it, pass the literal placeholder customers/DEFAULT/ (use a digit-free word like DEFAULT, a token containing any digit is treated as a real id, not a placeholder): when this connection captured a customer id at connect time, the gateway fills in the connected account automatically, for both the slash form (customers/DEFAULT/googleAds:search) and the colon form (customers/DEFAULT:mutate). If no id was captured (a manager/MCC login, a connection made before this feature, or a transient throttle at connect), the placeholder is NOT substituted and Google returns INVALID_CUSTOMER_ID, in that case retry with the real 10-digit id (find it in the top-right of the Google Ads UI). The substitution applies to the URL path ONLY: any customers/{id}/… resource_names inside the request body must use the real id. The listAccessibleCustomers GET endpoint is not available through this provider (it is POST-only). Do NOT send an Authorization header or a developer-token header, Pipedream injects both its developer token and the connected user’s Google credential automatically. This provider acts on the single Google Ads account you connect; manager-account (MCC) cross-account access is not supported here. GAQL is queried, not REST-resourced: select fields from a resource with optional WHERE/ORDER BY/LIMIT and date ranges (segments.date DURING LAST_30_DAYS). Mutations take an operations array (create/update/remove); updates also need update_mask. See https://developers.google.com/google-ads/api/rest/overview for the full reference. The endpoints below are curated examples.

Endpoints

Run a GAQL query against the connected account (googleAds:search). The workhorse read, list campaigns, ad groups, keywords, or pull metrics. Put the query in the body. Use this as a cheap auth probe after connect (e.g. select customer.id) to confirm the grant is healthy. Paginate with page_token from the response; cap rows with LIMIT or page_size.

POST https://googleads.googleapis.com/v21/customers/1234567890/googleAds:search — Free

SDK
cURL

const data = await lava.gateway('https://googleads.googleapis.com/v21/customers/1234567890/googleAds:search', {
  body: {
"query": "SELECT campaign.id, campaign.name, campaign.status, metrics.impressions, metrics.clicks, metrics.cost_micros FROM campaign WHERE segments.date DURING LAST_30_DAYS ORDER BY metrics.cost_micros DESC"
},
});

curl -X POST "https://api.lava.so/v1/forward?u=https%3A%2F%2Fgoogleads.googleapis.com%2Fv21%2Fcustomers%2F1234567890%2FgoogleAds%3Asearch" \
  -H "Authorization: Bearer $LAVA_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"SELECT campaign.id, campaign.name, campaign.status, metrics.impressions, metrics.clicks, metrics.cost_micros FROM campaign WHERE segments.date DURING LAST_30_DAYS ORDER BY metrics.cost_micros DESC"}'

List keywords and their performance with a GAQL query over the keyword_view resource. Filter by ad group, match type, or date range, and order by metrics to find top or wasted spend.

POST https://googleads.googleapis.com/v21/customers/1234567890/googleAds:search — Free

SDK
cURL

const data = await lava.gateway('https://googleads.googleapis.com/v21/customers/1234567890/googleAds:search', {
  body: {
"query": "SELECT ad_group_criterion.keyword.text, ad_group_criterion.keyword.match_type, metrics.clicks, metrics.cost_micros, metrics.conversions FROM keyword_view WHERE segments.date DURING LAST_30_DAYS ORDER BY metrics.cost_micros DESC LIMIT 50"
},
});

curl -X POST "https://api.lava.so/v1/forward?u=https%3A%2F%2Fgoogleads.googleapis.com%2Fv21%2Fcustomers%2F1234567890%2FgoogleAds%3Asearch" \
  -H "Authorization: Bearer $LAVA_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"SELECT ad_group_criterion.keyword.text, ad_group_criterion.keyword.match_type, metrics.clicks, metrics.cost_micros, metrics.conversions FROM keyword_view WHERE segments.date DURING LAST_30_DAYS ORDER BY metrics.cost_micros DESC LIMIT 50"}'

Create or update a campaign budget. A campaign needs a budget before it can run, so create the budget first and reference its resource_name from campaigns:mutate. amount_micros is the daily amount in micros (1,000,000 micros = 1 unit of account currency).

POST https://googleads.googleapis.com/v21/customers/1234567890/campaignBudgets:mutate — Free

SDK
cURL

const data = await lava.gateway('https://googleads.googleapis.com/v21/customers/1234567890/campaignBudgets:mutate', {
  body: {
"operations": [
  {
    "create": {
      "name": "Lava, Daily budget",
      "amount_micros": 50000000,
      "delivery_method": "STANDARD"
    }
  }
]
},
});

curl -X POST "https://api.lava.so/v1/forward?u=https%3A%2F%2Fgoogleads.googleapis.com%2Fv21%2Fcustomers%2F1234567890%2FcampaignBudgets%3Amutate" \
  -H "Authorization: Bearer $LAVA_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"operations":[{"create":{"name":"Lava, Daily budget","amount_micros":50000000,"delivery_method":"STANDARD"}}]}'

Create or update campaigns. Each operation is a create, update, or remove. For create, set name, an advertising_channel_type (e.g. SEARCH), a status (PAUSED is safest until reviewed), and campaign_budget (a budget resource_name from campaignBudgets:mutate). For update, set the campaign resource_name and an update_mask listing the fields you’re changing.

POST https://googleads.googleapis.com/v21/customers/1234567890/campaigns:mutate — Free

SDK
cURL

const data = await lava.gateway('https://googleads.googleapis.com/v21/customers/1234567890/campaigns:mutate', {
  body: {
"operations": [
  {
    "create": {
      "name": "Lava, Search, Brand",
      "advertising_channel_type": "SEARCH",
      "status": "PAUSED",
      "campaign_budget": "customers/1234567890/campaignBudgets/9876543210"
    }
  }
]
},
});

curl -X POST "https://api.lava.so/v1/forward?u=https%3A%2F%2Fgoogleads.googleapis.com%2Fv21%2Fcustomers%2F1234567890%2Fcampaigns%3Amutate" \
  -H "Authorization: Bearer $LAVA_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"operations":[{"create":{"name":"Lava, Search, Brand","advertising_channel_type":"SEARCH","status":"PAUSED","campaign_budget":"customers/1234567890/campaignBudgets/9876543210"}}]}'

Endpoints

List keywords and their performance with a GAQL query over the keyword_view resource. Filter by ad group, match type, or date range, and order by metrics to find top or wasted spend.

Create or update a campaign budget. A campaign needs a budget before it can run, so create the budget first and reference its resource_name from campaigns:mutate. amount_micros is the daily amount in micros (1,000,000 micros = 1 unit of account currency).

Next Steps

All Providers

Forward Proxy

​Endpoints

​List keywords and their performance with a GAQL query over the keyword_view resource. Filter by ad group, match type, or date range, and order by metrics to find top or wasted spend.

​Create or update a campaign budget. A campaign needs a budget before it can run, so create the budget first and reference its resource_name from campaigns:mutate. amount_micros is the daily amount in micros (1,000,000 micros = 1 unit of account currency).

​Next Steps

All Providers

Forward Proxy

Endpoints

List keywords and their performance with a GAQL query over the keyword_view resource. Filter by ad group, match type, or date range, and order by metrics to find top or wasted spend.

Create or update a campaign budget. A campaign needs a budget before it can run, so create the budget first and reference its resource_name from campaigns:mutate. amount_micros is the daily amount in micros (1,000,000 micros = 1 unit of account currency).

Next Steps