Google Ads

Use Google Ads in Agent Serve to list accessible accounts and campaigns, retrieve ad groups and performance metrics, and run custom Google Ads Query Language (GAQL) queries. These read operations support campaign reporting and budget monitoring workflows.

Usage Instructions

Connect to Google Ads to list accounts, campaigns, and ad groups, get performance metrics, and run custom GAQL queries. Start a workflow when someone submits a lead form, and send qualified or won leads back to Google Ads as offline conversions so bidding favors better leads. Use Ingest Offline Conversions or Ingest Enhanced Conversions for Leads, which go through Google's Data Manager API; the older Upload operations only work for Google Cloud projects Google has allowlisted.

Actions

List Google Ads Customers

List all Google Ads customer accounts accessible by the authenticated user

Input

ParameterTypeRequiredDescription
developerTokenstringNoGoogle Ads API developer token (optional: Google sunset developer tokens on September 9, 2026 and ignores them)

Output

ParameterTypeDescription
customerIdsarrayList of accessible customer IDs
totalCountnumberTotal number of accessible customer accounts

Run a custom Google Ads Query Language (GAQL) query

Input

ParameterTypeRequiredDescription
customerIdstringYesGoogle Ads customer ID (numeric, no dashes)
developerTokenstringNoGoogle Ads API developer token (optional: Google sunset developer tokens on September 9, 2026 and ignores them)
managerCustomerIdstringNoManager account customer ID (if accessing via manager account)
querystringYesGAQL query to execute
pageTokenstringNoPage token for pagination

Output

ParameterTypeDescription
resultsjsonArray of result objects from the GAQL query
totalResultsCountnumberTotal number of matching results
nextPageTokenstringToken for the next page of results

List Google Ads Campaigns

List campaigns in a Google Ads account with optional status filtering

Input

ParameterTypeRequiredDescription
customerIdstringYesGoogle Ads customer ID (numeric, no dashes)
developerTokenstringNoGoogle Ads API developer token (optional: Google sunset developer tokens on September 9, 2026 and ignores them)
managerCustomerIdstringNoManager account customer ID (if accessing via manager account)
statusstringNoFilter by campaign status (ENABLED, PAUSED, REMOVED)
limitnumberNoMaximum number of campaigns to return

Output

ParameterTypeDescription
campaignsarrayList of campaigns in the account
↳ idstringCampaign ID
↳ namestringCampaign name
↳ statusstringCampaign status (ENABLED, PAUSED, REMOVED)
↳ channelTypestringAdvertising channel type (SEARCH, DISPLAY, SHOPPING, VIDEO, PERFORMANCE_MAX)
↳ startDatestringCampaign start date (YYYY-MM-DD)
↳ endDatestringCampaign end date (YYYY-MM-DD)
↳ budgetAmountMicrosstringDaily budget in micros (divide by 1,000,000 for currency value)
totalCountnumberTotal number of campaigns returned

Get performance metrics for Google Ads campaigns over a date range

Input

ParameterTypeRequiredDescription
customerIdstringYesGoogle Ads customer ID (numeric, no dashes)
developerTokenstringNoGoogle Ads API developer token (optional: Google sunset developer tokens on September 9, 2026 and ignores them)
managerCustomerIdstringNoManager account customer ID (if accessing via manager account)
campaignIdstringNoFilter by specific campaign ID
dateRangestringNoPredefined date range (LAST_7_DAYS, LAST_30_DAYS, THIS_MONTH, LAST_MONTH, TODAY, YESTERDAY)
startDatestringNoCustom start date in YYYY-MM-DD format
endDatestringNoCustom end date in YYYY-MM-DD format

Output

ParameterTypeDescription
campaignsarrayCampaign performance data broken down by date
↳ idstringCampaign ID
↳ namestringCampaign name
↳ statusstringCampaign status
↳ impressionsstringNumber of impressions
↳ clicksstringNumber of clicks
↳ costMicrosstringCost in micros (divide by 1,000,000 for currency value)
↳ ctrnumberClick-through rate (0.0 to 1.0)
↳ conversionsnumberNumber of conversions
↳ datestringDate for this row (YYYY-MM-DD)
totalCountnumberTotal number of result rows

List Google Ads Ad Groups

List ad groups in a Google Ads campaign

Input

ParameterTypeRequiredDescription
customerIdstringYesGoogle Ads customer ID (numeric, no dashes)
developerTokenstringNoGoogle Ads API developer token (optional: Google sunset developer tokens on September 9, 2026 and ignores them)
managerCustomerIdstringNoManager account customer ID (if accessing via manager account)
campaignIdstringYesCampaign ID to list ad groups for
statusstringNoFilter by ad group status (ENABLED, PAUSED, REMOVED)
limitnumberNoMaximum number of ad groups to return

Output

ParameterTypeDescription
adGroupsarrayList of ad groups in the campaign
↳ idstringAd group ID
↳ namestringAd group name
↳ statusstringAd group status (ENABLED, PAUSED, REMOVED)
↳ typestringAd group type (SEARCH_STANDARD, DISPLAY_STANDARD, SHOPPING_PRODUCT_ADS)
↳ campaignIdstringParent campaign ID
↳ campaignNamestringParent campaign name
totalCountnumberTotal number of ad groups returned

Get performance metrics for individual ads over a date range

Input

ParameterTypeRequiredDescription
customerIdstringYesGoogle Ads customer ID (numeric, no dashes)
developerTokenstringNoGoogle Ads API developer token (optional: Google sunset developer tokens on September 9, 2026 and ignores them)
managerCustomerIdstringNoManager account customer ID (if accessing via manager account)
campaignIdstringNoFilter by campaign ID
adGroupIdstringNoFilter by ad group ID
dateRangestringNoPredefined date range (LAST_7_DAYS, LAST_30_DAYS, THIS_MONTH, LAST_MONTH, TODAY, YESTERDAY)
startDatestringNoCustom start date in YYYY-MM-DD format
endDatestringNoCustom end date in YYYY-MM-DD format
limitnumberNoMaximum number of results to return

Output

ParameterTypeDescription
adsarrayAd performance data broken down by date
↳ adIdstringAd ID
↳ adGroupIdstringParent ad group ID
↳ adGroupNamestringParent ad group name
↳ campaignIdstringParent campaign ID
↳ campaignNamestringParent campaign name
↳ adTypestringAd type (RESPONSIVE_SEARCH_AD, EXPANDED_TEXT_AD, etc.)
↳ impressionsstringNumber of impressions
↳ clicksstringNumber of clicks
↳ costMicrosstringCost in micros (divide by 1,000,000 for currency value)
↳ ctrnumberClick-through rate (0.0 to 1.0)
↳ conversionsnumberNumber of conversions
↳ datestringDate for this row (YYYY-MM-DD)
totalCountnumberTotal number of result rows

List Google Ads Conversion Actions

List conversion actions in a Google Ads account, with their resource names for conversion uploads

Input

ParameterTypeRequiredDescription
customerIdstringYesGoogle Ads customer ID (numeric, no dashes)
developerTokenstringNoGoogle Ads API developer token (optional: Google sunset developer tokens on September 9, 2026 and ignores them)
managerCustomerIdstringNoManager account customer ID (if accessing via manager account)
conversionActionTypestringNoOnly list actions of this type, e.g. UPLOAD_CLICKS for actions that accept offline click conversion imports
limitnumberNoMaximum number of conversion actions to return

Output

ParameterTypeDescription
conversionActionsarrayConversion actions in the account (removed actions are excluded)
↳ idstringConversion action ID
↳ namestringConversion action name
↳ resourceNamestringResource name (customers/{customerId}/conversionActions/{id}) to pass to conversion uploads
↳ typestringConversion action type, e.g. UPLOAD_CLICKS for offline click imports
↳ statusstringStatus (ENABLED or HIDDEN)
↳ categorystringCategory, e.g. QUALIFIED_LEAD or PURCHASE
↳ primaryForGoalbooleanWhether the action is primary for its goal and used for bidding
↳ defaultValuenumberDefault conversion value
↳ defaultCurrencyCodestringDefault currency code
↳ alwaysUseDefaultValuebooleanWhether the default value always replaces uploaded values
totalCountnumberNumber of conversion actions returned

Ingest Google Ads Offline Conversions

Send offline click conversions (for example qualified or won leads) to Google Ads by gclid, gbraid, or wbraid through the Data Manager API, so bidding learns which clicks turn into business. Recommended over Upload Click Conversions, which Google limits to allowlisted projects.

Input

ParameterTypeRequiredDescription
customerIdstringYesGoogle Ads customer ID that owns the conversion action (numeric, no dashes)
managerCustomerIdstringNoManager account customer ID, when the connected Google account reaches the customer through a manager
conversionActionstringYesConversion action ID, or its resource name (customers/{customerId}/conversionActions/{id}). Must be an UPLOAD_CLICKS action ("Website (Import from clicks)"). A row can override it.
eventSourcestringNoWhere the conversion happened: WEB, APP, IN_STORE, PHONE, MESSAGE, OTHER. Defaults to WEB. A row can override it.
gclidstringNoGoogle click ID captured from the landing page URL (single-row upload)
gbraidstringNogbraid URL parameter for iOS app clicks (single-row upload)
wbraidstringNowbraid URL parameter for iOS web clicks (single-row upload)
conversionDateTimestringNoWhen the conversion happened, with a timezone: ISO 8601 such as "2026-06-01T14:30:00-04:00", or "2026-06-01 14:30:00-04:00" (single-row upload)
conversionValuenumberNoConversion value in currency units, not micros (single-row upload)
currencyCodestringNoISO 4217 currency code for the value, e.g. USD (single-row upload)
orderIdstringNoUnique order or lead ID, sent as the transaction ID; Google uses it to deduplicate (single-row upload)
adUserDataConsentstringNoConsent for ad user data for every row: GRANTED or DENIED. A row can override it.
adPersonalizationConsentstringNoConsent for ad personalization for every row: GRANTED or DENIED. A row can override it.
validateOnlybooleanNoValidate the rows with Google without importing them
conversionsjsonNoUp to 2,000 rows to send at once, replacing the single-row fields. Each row: { gclid | gbraid | wbraid, conversionDateTime, conversionValue?, currencyCode?, orderId?, conversionAction?, eventSource?, adUserDataConsent?, adPersonalizationConsent? }

Output

ParameterTypeDescription
customerIdsjsonList of accessible customer IDs (list_customers)
resultsjsonQuery results (search), or rows Google accepted (conversion uploads and adjustments)
conversionActionsjsonConversion actions with their resource names (list_conversion_actions)
uploadedCountnumberRows Google accepted (conversion uploads and adjustments)
failedCountnumberRows Google rejected (conversion uploads and adjustments)
errorsjsonRow-level errors: index, type, code, message, field (conversion uploads)
jobIdstringUpload job ID for the offline diagnostics report (conversion uploads)
validateOnlybooleanWhether the upload was only validated (conversion uploads and ingests)
requestIdstringData Manager request ID to pass to Get Ingest Status (ingests, ingest status)
eventCountnumberConversion events sent (ingests)
destinationCountnumberConversion actions the events were sent to (ingests)
warningsjsonField warnings on accepted events: index, field, reason, description (ingests)
requestStatusstringPROCESSING, SUCCESS, PARTIAL_SUCCESS, FAILED, or REQUEST_STATUS_UNKNOWN (get_ingest_status)
destinationsjsonPer conversion action: status, event count, and error and warning counts by reason (get_ingest_status)
campaignsjsonCampaign data (list_campaigns, campaign_performance)
adGroupsjsonAd group data (list_ad_groups)
adsjsonAd performance data (ad_performance)
totalCountnumberTotal number of results
totalResultsCountnumberTotal results count (search)
nextPageTokenstringToken for next page of results

Ingest Google Ads Enhanced Conversions for Leads

Send offline lead conversions matched by the lead's email or phone through the Data Manager API. Agent Serve normalizes and SHA-256 hashes them before sending, so raw contact data never leaves Agent Serve. Recommended over Upload Enhanced Conversions for Leads, which Google limits to allowlisted projects.

Input

ParameterTypeRequiredDescription
customerIdstringYesGoogle Ads customer ID that owns the conversion action (numeric, no dashes)
managerCustomerIdstringNoManager account customer ID, when the connected Google account reaches the customer through a manager
conversionActionstringYesConversion action ID, or its resource name (customers/{customerId}/conversionActions/{id}). Must be an UPLOAD_CLICKS action ("Website (Import from clicks)"). A row can override it.
eventSourcestringNoWhere the conversion happened: WEB, APP, IN_STORE, PHONE, MESSAGE, OTHER. Defaults to WEB. A row can override it.
gclidstringNoGoogle click ID captured from the landing page URL (single-row upload)
gbraidstringNogbraid URL parameter for iOS app clicks (single-row upload)
wbraidstringNowbraid URL parameter for iOS web clicks (single-row upload)
conversionDateTimestringNoWhen the conversion happened, with a timezone: ISO 8601 such as "2026-06-01T14:30:00-04:00", or "2026-06-01 14:30:00-04:00" (single-row upload)
conversionValuenumberNoConversion value in currency units, not micros (single-row upload)
currencyCodestringNoISO 4217 currency code for the value, e.g. USD (single-row upload)
orderIdstringNoUnique order or lead ID, sent as the transaction ID; Google uses it to deduplicate (single-row upload)
adUserDataConsentstringNoConsent for ad user data for every row: GRANTED or DENIED. A row can override it.
adPersonalizationConsentstringNoConsent for ad personalization for every row: GRANTED or DENIED. A row can override it.
validateOnlybooleanNoValidate the rows with Google without importing them
emailstringNoLead's email address, hashed with SHA-256 before sending (single-row upload; email or phone required)
phoneNumberstringNoLead's phone number with country code, e.g. +14155550123; hashed with SHA-256 before sending (single-row upload)
sessionAttributesstringNoBase64 session attributes string captured with the lead form submission, which Google recommends sending (single-row upload)
conversionsjsonNoUp to 2,000 rows to send at once, replacing the single-row fields. Each row: { email?, phoneNumber?, gclid?, sessionAttributes?, conversionDateTime, conversionValue?, currencyCode?, orderId?, conversionAction?, eventSource?, adUserDataConsent?, adPersonalizationConsent? } with an email or phone

Output

ParameterTypeDescription
customerIdsjsonList of accessible customer IDs (list_customers)
resultsjsonQuery results (search), or rows Google accepted (conversion uploads and adjustments)
conversionActionsjsonConversion actions with their resource names (list_conversion_actions)
uploadedCountnumberRows Google accepted (conversion uploads and adjustments)
failedCountnumberRows Google rejected (conversion uploads and adjustments)
errorsjsonRow-level errors: index, type, code, message, field (conversion uploads)
jobIdstringUpload job ID for the offline diagnostics report (conversion uploads)
validateOnlybooleanWhether the upload was only validated (conversion uploads and ingests)
requestIdstringData Manager request ID to pass to Get Ingest Status (ingests, ingest status)
eventCountnumberConversion events sent (ingests)
destinationCountnumberConversion actions the events were sent to (ingests)
warningsjsonField warnings on accepted events: index, field, reason, description (ingests)
requestStatusstringPROCESSING, SUCCESS, PARTIAL_SUCCESS, FAILED, or REQUEST_STATUS_UNKNOWN (get_ingest_status)
destinationsjsonPer conversion action: status, event count, and error and warning counts by reason (get_ingest_status)
campaignsjsonCampaign data (list_campaigns, campaign_performance)
adGroupsjsonAd group data (list_ad_groups)
adsjsonAd performance data (ad_performance)
totalCountnumberTotal number of results
totalResultsCountnumberTotal results count (search)
nextPageTokenstringToken for next page of results

Get Google Ads Ingest Status

Check how Google processed a Data Manager conversion request: success, partial success, failure, or still processing, with error and warning counts per reason. Statuses appear about 30 minutes after ingesting and can take up to 24 hours.

Input

ParameterTypeRequiredDescription
requestIdstringYesRequest ID returned by an ingest operation

Output

ParameterTypeDescription
requestIdstringRequest ID that was checked
requestStatusstringOverall status: PROCESSING, SUCCESS, PARTIAL_SUCCESS, FAILED, or REQUEST_STATUS_UNKNOWN
destinationsarrayStatus per conversion action, in the order of the original request

Upload Google Ads Click Conversions

Import offline click conversions (for example qualified or won leads) to Google Ads by gclid, gbraid, or wbraid, so bidding learns which clicks turn into business. Needs a Google Cloud project that Google allowlisted for offline conversion import; use Ingest Offline Conversions otherwise.

Input

ParameterTypeRequiredDescription
customerIdstringYesGoogle Ads customer ID (numeric, no dashes)
developerTokenstringNoGoogle Ads API developer token (optional: Google sunset developer tokens on September 9, 2026 and ignores them)
managerCustomerIdstringNoManager account customer ID (if accessing via manager account)
conversionActionstringYesConversion action resource name (customers/{customerId}/conversionActions/{id}) or numeric ID. Must be an enabled UPLOAD_CLICKS action. A row can override it.
gclidstringNoGoogle click ID captured from the landing page URL (single-row upload)
gbraidstringNogbraid URL parameter for clicks that led to an iOS app (single-row upload)
wbraidstringNowbraid URL parameter for iOS app clicks that led to the web (single-row upload)
conversionDateTimestringNoWhen the conversion happened, after the click, with a timezone: "2026-06-01 14:30:00-04:00" or ISO 8601 (single-row upload)
conversionValuenumberNoConversion value (single-row upload)
currencyCodestringNoISO 4217 currency code for the value, e.g. USD (single-row upload)
orderIdstringNoUnique order or lead ID; prevents duplicate imports and is needed to retract or restate later (single-row upload)
adUserDataConsentstringNoConsent for ad user data: GRANTED or DENIED
validateOnlybooleanNoValidate the rows without importing them
conversionsjsonNoUp to 2,000 rows to upload at once, replacing the single-row fields. Each row: { gclid | gbraid | wbraid, conversionDateTime, conversionValue?, currencyCode?, orderId?, conversionAction?, adUserDataConsent? }

Output

ParameterTypeDescription
resultsarrayRows Google accepted
↳ indexnumberZero-based row index in the request
↳ conversionActionstringConversion action resource name
↳ conversionDateTimestringConversion date time
↳ gclidstringGoogle click ID
↳ gbraidstringgbraid URL parameter
↳ wbraidstringwbraid URL parameter

Upload Google Ads Enhanced Conversions for Leads

Import offline lead conversions matched by the lead's email or phone. Agent Serve normalizes and SHA-256 hashes them before sending, so raw contact data never leaves Agent Serve. Needs a Google Cloud project that Google allowlisted for offline conversion import; use Ingest Enhanced Conversions for Leads otherwise.

Input

ParameterTypeRequiredDescription
customerIdstringYesGoogle Ads customer ID (numeric, no dashes)
developerTokenstringNoGoogle Ads API developer token (optional: Google sunset developer tokens on September 9, 2026 and ignores them)
managerCustomerIdstringNoManager account customer ID (if accessing via manager account)
conversionActionstringYesConversion action resource name (customers/{customerId}/conversionActions/{id}) or numeric ID. Must be an enabled UPLOAD_CLICKS action. A row can override it.
gclidstringNoGoogle click ID captured from the landing page URL (single-row upload)
gbraidstringNogbraid URL parameter for clicks that led to an iOS app (single-row upload)
wbraidstringNowbraid URL parameter for iOS app clicks that led to the web (single-row upload)
conversionDateTimestringNoWhen the conversion happened, after the click, with a timezone: "2026-06-01 14:30:00-04:00" or ISO 8601 (single-row upload)
conversionValuenumberNoConversion value (single-row upload)
currencyCodestringNoISO 4217 currency code for the value, e.g. USD (single-row upload)
orderIdstringNoUnique order or lead ID; prevents duplicate imports and is needed to retract or restate later (single-row upload)
adUserDataConsentstringNoConsent for ad user data: GRANTED or DENIED
validateOnlybooleanNoValidate the rows without importing them
emailstringNoLead's email address, hashed with SHA-256 before upload (single-row upload; email or phone required)
phoneNumberstringNoLead's phone number with country code, e.g. +14155550123; hashed with SHA-256 before upload (single-row upload)
conversionsjsonNoUp to 2,000 rows to upload at once, replacing the single-row fields. Each row: { email?, phoneNumber?, gclid?, conversionDateTime, conversionValue?, currencyCode?, orderId?, conversionAction?, adUserDataConsent? } with an email or phone

Output

ParameterTypeDescription
resultsarrayRows Google accepted
↳ indexnumberZero-based row index in the request
↳ conversionActionstringConversion action resource name
↳ conversionDateTimestringConversion date time
↳ gclidstringGoogle click ID, when supplied
↳ gbraidstringgbraid URL parameter, when supplied
↳ wbraidstringwbraid URL parameter, when supplied

Adjust Google Ads Conversions

Retract an uploaded conversion (for example a lead that turned out to be junk) or restate its value (for example the final deal size)

Input

ParameterTypeRequiredDescription
customerIdstringYesGoogle Ads customer ID (numeric, no dashes)
developerTokenstringNoGoogle Ads API developer token (optional: Google sunset developer tokens on September 9, 2026 and ignores them)
managerCustomerIdstringNoManager account customer ID (if accessing via manager account)
conversionActionstringYesConversion action resource name or numeric ID of the original conversion. A row can override it.
adjustmentTypestringNoRETRACTION zeroes the conversion; RESTATEMENT changes its value (single-row adjustment)
orderIdstringNoOrder ID the conversion was uploaded with; required if it had one (single-row adjustment)
gclidstringNoGoogle click ID of a conversion uploaded without an order ID (single-row adjustment)
conversionDateTimestringNoOriginal conversion date time, required with gclid: "2026-06-01 14:30:00-04:00" or ISO 8601
adjustmentDateTimestringNoWhen the adjustment happened, after the conversion, with a timezone (single-row adjustment)
adjustedValuenumberNoNew conversion value; required for a restatement, not allowed for a retraction
currencyCodestringNoISO 4217 currency code of the restated value, e.g. USD
adjustmentsjsonNoUp to 2,000 rows to adjust at once, replacing the single-row fields. Each row: { adjustmentType, orderId | (gclid + conversionDateTime), adjustmentDateTime, adjustedValue?, currencyCode?, conversionAction? }
validateOnlybooleanNoValidate the rows without applying them

Output

ParameterTypeDescription
resultsarrayAdjustments Google accepted
↳ indexnumberZero-based row index in the request
↳ adjustmentTypestringRETRACTION or RESTATEMENT
↳ conversionActionstringConversion action resource name
↳ adjustmentDateTimestringAdjustment date time
↳ orderIdstringOrder ID of the adjusted conversion
↳ gclidstringGoogle click ID of the adjusted conversion
↳ conversionDateTimestringDate time of the adjusted conversion

Triggers

A Trigger is a block that starts a workflow when an event happens in this service.

Trigger workflow when someone submits a Google Ads lead form, with their answers keyed by column ID

Configuration

ParameterTypeRequiredDescription
googleKeystringYesThe same key you enter in the lead form’s webhook settings in Google Ads. Deliveries with a different key are rejected.

Output

ParameterTypeDescription
leadIdstringUnique lead ID; use it to deduplicate
fieldsjsonSubmitted answers keyed by column ID, e.g. { "FULL_NAME": "Jane Doe", "EMAIL": "jane@example.com", "PHONE_NUMBER": "+14155550123" }
columnsjsonSubmitted answers in form order, each { columnId, columnName, value }; columnName is the question text when Google sends it
fullNamestringFULL_NAME, or FIRST_NAME and LAST_NAME joined, when the form asked for them
emailstringEMAIL, or WORK_EMAIL when only that was asked
phoneNumberstringPHONE_NUMBER, or WORK_PHONE when only that was asked
isTestbooleanTrue for test leads sent from the Google Ads UI
gclidstringGoogle click ID of the lead; pass it to conversion uploads
formIdstringLead form ID
campaignIdstringCampaign ID
adGroupIdstringAd group ID (video and discovery ads only)
creativeIdstringCreative ID (video and discovery ads only)
assetGroupIdstringAsset group ID (Performance Max campaigns only)
leadSubmitTimestringWhen the lead was submitted, ISO 8601 (e.g. 2024-09-26T12:30:00Z)
leadStagestringLead stage at the time of delivery
leadSourcestringWhere the lead came from: LEAD_FORM or CONVERSATIONAL_AGENT
apiVersionstringWebhook payload version
payloadjsonFull lead payload as Google sent it, without the google_key