Google Ads Integration

Overview

Add Google Ads to any ModuleX agent or workflow. Google Ads API integration covering GAQL reports across Campaigns, Ad Groups, Ads, and Customers; Customer Match list management; offline conversion uploads; and keyword idea generation against the REST API at googleads.googleapis.com.

Categories: Marketing & Advertising · Analytics · Business Services · Auth: OAuth2 · Actions: 10

Authentication

OAuth2 Authentication

Connect using Google OAuth2 (recommended). Requires a Google Ads API developer token in addition to the OAuth credentials.

Required Credentials

Field	Description	Required	Format
Client ID	Google OAuth2 Client ID from Cloud Console.	Yes	`123456789-xxxxxxxxxxxxxxxx.apps.googleusercontent.com`
Client Secret	Google OAuth2 Client Secret.	Yes	`GOCSPX-xxxxxxxxxxxxxxxxxxxx`
Developer Token	Google Ads API developer-token header value. Apply at https://ads.google.com/aw/apicenter (Manager Account required).	Yes	`xxxxxxxxxxxxxxxxxxxxxx`

OAuth Configuration

Authorization URL: https://accounts.google.com/o/oauth2/v2/auth
Token URL: https://oauth2.googleapis.com/token
Scopes: https://www.googleapis.com/auth/adwords

Available Actions

add_contact_to_list_by_email — Add a contact to a Google Ads Customer Match user list by email. Lists typically update in 6 to 12 hours. The email is SHA-256 hashed locally before upload.

Parameters

string

required

string

required

ID of the CRM-based customer list to update.

string

required

Email address of the contact to add.

string

Managed customer (client) ID. Defaults to account_id when omitted.

Response

{
  "additionalProperties": false,
  "properties": {
    "success": {
      "title": "Success",
      "type": "boolean"
    },
    "error": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Error"
    },
    "offline_user_data_job_resource_name": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Offline User Data Job Resource Name"
    },
    "operation_resource_name": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Operation Resource Name"
    }
  },
  "required": [
    "success"
  ],
  "title": "AddContactToListByEmailOutput",
  "type": "object"
}

create_ad_group_report — Run a GAQL search report for the ad_group resource via GoogleAdsService.search.

Parameters

string

required

array

List of ad_group fields to select (e.g. ‘ad_group.id’, ‘ad_group.name’). Each element is a string; the ‘ad_group.’ prefix is auto-added if missing.

array

List of segments (e.g. ‘segments.date’). Each element is a string; the ‘segments.’ prefix is auto-added.

array

List of metric fields (e.g. ‘metrics.clicks’). Each element is a string; the ‘metrics.’ prefix is auto-added.

array

Optional list of ad_group IDs to filter by. Each element is a string (the numeric ID).

string

Date range constant: CUSTOM, TODAY, YESTERDAY, LAST_7_DAYS, LAST_14_DAYS, LAST_30_DAYS, THIS_MONTH, LAST_MONTH, THIS_WEEK_SUN_TODAY, THIS_WEEK_MON_TODAY, LAST_WEEK_SUN_SAT, LAST_WEEK_MON_SUN, LAST_BUSINESS_WEEK.

string

Custom range start (YYYY-MM-DD); required when date_range=CUSTOM.

string

Custom range end (YYYY-MM-DD); required when date_range=CUSTOM.

string

Field name to order results by.

string

Order direction: ASC or DESC. (Default: ASC)

integer

Maximum number of results to return.

string

Managed customer ID; defaults to account_id when omitted.

Response

{
  "additionalProperties": false,
  "properties": {
    "success": {
      "title": "Success",
      "type": "boolean"
    },
    "error": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Error"
    },
    "query": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Query"
    },
    "results": {
      "items": {
        "additionalProperties": true,
        "type": "object"
      },
      "title": "Results",
      "type": "array"
    },
    "field_mask": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Field Mask"
    },
    "request_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Request Id"
    }
  },
  "required": [
    "success"
  ],
  "title": "CreateAdGroupReportOutput",
  "type": "object"
}

create_ad_report — Run a GAQL search report for the ad_group_ad resource via GoogleAdsService.search.

Parameters

string

required

array

List of ad_group_ad fields to select (strings).

array

List of segments (strings).

array

List of metric fields (strings).

array

Optional list of ad IDs to filter by (strings).

string

Date range constant. See create_ad_group_report for valid values.

string

Custom range start (YYYY-MM-DD); required when date_range=CUSTOM.

string

Custom range end (YYYY-MM-DD); required when date_range=CUSTOM.

string

Field name to order results by.

string

Order direction: ASC or DESC. (Default: ASC)

integer

Maximum number of results to return.

string

Managed customer ID; defaults to account_id when omitted.

Response

{
  "additionalProperties": false,
  "properties": {
    "success": {
      "title": "Success",
      "type": "boolean"
    },
    "error": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Error"
    },
    "query": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Query"
    },
    "results": {
      "items": {
        "additionalProperties": true,
        "type": "object"
      },
      "title": "Results",
      "type": "array"
    },
    "field_mask": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Field Mask"
    },
    "request_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Request Id"
    }
  },
  "required": [
    "success"
  ],
  "title": "CreateAdReportOutput",
  "type": "object"
}

create_campaign_report — Run a GAQL search report for the campaign resource via GoogleAdsService.search.

Parameters

string

required

array

List of campaign fields to select (strings).

array

List of segments (strings).

array

List of metric fields (strings).

array

Optional list of campaign IDs to filter by (strings).

string

Date range constant. See create_ad_group_report for valid values.

string

Custom range start (YYYY-MM-DD); required when date_range=CUSTOM.

string

Custom range end (YYYY-MM-DD); required when date_range=CUSTOM.

string

Field name to order results by.

string

Order direction: ASC or DESC. (Default: ASC)

integer

Maximum number of results to return.

string

Managed customer ID; defaults to account_id when omitted.

Response

{
  "additionalProperties": false,
  "properties": {
    "success": {
      "title": "Success",
      "type": "boolean"
    },
    "error": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Error"
    },
    "query": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Query"
    },
    "results": {
      "items": {
        "additionalProperties": true,
        "type": "object"
      },
      "title": "Results",
      "type": "array"
    },
    "field_mask": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Field Mask"
    },
    "request_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Request Id"
    }
  },
  "required": [
    "success"
  ],
  "title": "CreateCampaignReportOutput",
  "type": "object"
}

create_customer_list — Create a Google Ads UserList (CRM_BASED / RULE_BASED / LOGICAL / BASIC_USER_LIST / LOOKALIKE). Returns the new user list ID and resource name.

Parameters

string

required

string

required

Name of the user list.

string

required

Which UserList variant to create. One of: crmBasedUserList, ruleBasedUserList, logicalUserList, basicUserList, lookalikeUserList. Determines which fields list_type_data should populate.

object

Variant-specific payload. Merged under the list_type key. See https://developers.google.com/google-ads/api/reference/rpc/v21/UserList for the per-variant schema. (Default: {})

string

Optional description of the user list.

object

Additional top-level UserList fields to merge into the create payload (e.g. membershipLifeSpan). (Default: {})

string

Managed customer ID; defaults to account_id when omitted.

Response

{
  "additionalProperties": false,
  "properties": {
    "success": {
      "title": "Success",
      "type": "boolean"
    },
    "error": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Error"
    },
    "id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Id"
    },
    "resource_name": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Resource Name"
    }
  },
  "required": [
    "success"
  ],
  "title": "CreateCustomerListOutput",
  "type": "object"
}

create_customer_report — Run a GAQL search report for the customer resource via GoogleAdsService.search.

Parameters

string

required

array

List of customer fields to select (strings).

array

List of segments (strings).

array

List of metric fields (strings).

array

Optional list of customer IDs to filter by (strings).

string

Date range constant. See create_ad_group_report for valid values.

string

Custom range start (YYYY-MM-DD); required when date_range=CUSTOM.

string

Custom range end (YYYY-MM-DD); required when date_range=CUSTOM.

string

Field name to order results by.

string

Order direction: ASC or DESC. (Default: ASC)

integer

Maximum number of results to return.

string

Managed customer ID; defaults to account_id when omitted.

Response

{
  "additionalProperties": false,
  "properties": {
    "success": {
      "title": "Success",
      "type": "boolean"
    },
    "error": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Error"
    },
    "query": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Query"
    },
    "results": {
      "items": {
        "additionalProperties": true,
        "type": "object"
      },
      "title": "Results",
      "type": "array"
    },
    "field_mask": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Field Mask"
    },
    "request_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Request Id"
    }
  },
  "required": [
    "success"
  ],
  "title": "CreateCustomerReportOutput",
  "type": "object"
}

create_report — Run a GAQL search report against any resource via GoogleAdsService.search. Builds a SELECT/WHERE/ORDER/LIMIT query from the supplied fields/segments/metrics.

Parameters

string

required

string

required

Resource name to FROM-clause against (e.g. campaign, ad_group, ad_group_ad, customer).

array

List of resource fields to select (strings). The resource prefix is auto-added if missing.

array

List of segments (strings).

array

List of metric fields (strings).

array

Optional list of resource IDs to filter by (strings).

string

Date range constant. See create_ad_group_report for valid values.

string

Custom range start (YYYY-MM-DD); required when date_range=CUSTOM.

string

Custom range end (YYYY-MM-DD); required when date_range=CUSTOM.

string

Field name to order results by.

string

Order direction: ASC or DESC. (Default: ASC)

integer

Maximum number of results to return.

string

Managed customer ID; defaults to account_id when omitted.

Response

{
  "additionalProperties": false,
  "properties": {
    "success": {
      "title": "Success",
      "type": "boolean"
    },
    "error": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Error"
    },
    "query": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Query"
    },
    "results": {
      "items": {
        "additionalProperties": true,
        "type": "object"
      },
      "title": "Results",
      "type": "array"
    },
    "field_mask": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Field Mask"
    },
    "request_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Request Id"
    }
  },
  "required": [
    "success"
  ],
  "title": "CreateReportOutput",
  "type": "object"
}

generate_keyword_ideas — Generate keyword ideas via KeywordPlanIdeaService.generateKeywordIdeas. Pass the GenerateKeywordIdeasRequest body fields under additional_fields.

Parameters

string

required

string

required

Managed customer ID to run the request against (required by the keyword ideas service).

object

Body of the GenerateKeywordIdeasRequest. See https://developers.google.com/google-ads/api/reference/rpc/v22/KeywordPlanIdeaService/GenerateKeywordIdeas for the required structure (e.g. language, geoTargetConstants, keywordSeed). (Default: {})

Response

{
  "additionalProperties": false,
  "properties": {
    "success": {
      "title": "Success",
      "type": "boolean"
    },
    "error": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Error"
    },
    "results": {
      "items": {
        "additionalProperties": true,
        "type": "object"
      },
      "title": "Results",
      "type": "array"
    },
    "total_size": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Total Size"
    },
    "next_page_token": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Next Page Token"
    }
  },
  "required": [
    "success"
  ],
  "title": "GenerateKeywordIdeasOutput",
  "type": "object"
}

list_account_id_options — List customer resources directly accessible by the authenticated user via CustomerService.ListAccessibleCustomers. Useful to discover candidate account_id values.

Response

{
  "$defs": {
    "AccessibleCustomer": {
      "additionalProperties": false,
      "description": "One entry returned from ``customers:listAccessibleCustomers``.",
      "properties": {
        "resource_name": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Resource Name"
        },
        "customer_id": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Customer Id"
        }
      },
      "title": "AccessibleCustomer",
      "type": "object"
    }
  },
  "additionalProperties": false,
  "properties": {
    "success": {
      "title": "Success",
      "type": "boolean"
    },
    "error": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Error"
    },
    "customers": {
      "items": {
        "$ref": "#/$defs/AccessibleCustomer"
      },
      "title": "Customers",
      "type": "array"
    }
  },
  "required": [
    "success"
  ],
  "title": "ListAccountIdOptionsOutput",
  "type": "object"
}

send_offline_conversion — Create a ConversionAction (offline conversion tracking) via ConversionActionService.mutate.

Parameters

string

required

string

required

Name of the conversion action.

string

required

ConversionActionType enum value (e.g. UPLOAD_CLICKS, UPLOAD_CALLS, WEBPAGE). See https://developers.google.com/google-ads/api/reference/rpc/v21/ConversionActionTypeEnum.ConversionActionType.

object

Additional ConversionAction fields to merge into the create payload (e.g. category, status, valueSettings). (Default: {})

string

Managed customer ID; defaults to account_id when omitted.

Response

{
  "additionalProperties": false,
  "properties": {
    "success": {
      "title": "Success",
      "type": "boolean"
    },
    "error": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Error"
    },
    "id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Id"
    },
    "resource_name": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Resource Name"
    }
  },
  "required": [
    "success"
  ],
  "title": "SendOfflineConversionOutput",
  "type": "object"
}

Limits & Quotas

Daily operations quota depends on the developer-token access level (Test, Basic, Standard). Standard tokens allow 15,000 operations/day initially. See https://developers.google.com/google-ads/api/docs/access-levels.
Customer Match lists typically take 6 to 12 hours to update after add_contact_to_list_by_email runs.
generate_keyword_ideas counts against the same quota and may be rate-limited per minute on Basic-access tokens.
Error model: non-2xx responses and timeouts are caught and returned as success=False + error rather than raising. The error string includes the API status code and body excerpt.

Using

Providers

Building

Tools

Google Ads Integration for AI Agents & Workflows

Overview

Authentication

OAuth2 Authentication

Required Credentials

OAuth Configuration

Available Actions

Parameters

Response

Parameters

Response

Parameters

Response

Parameters

Response

Parameters

Response

Parameters

Response

Parameters

Response

Parameters

Response

Response

Parameters

Response

Limits & Quotas

PostGrid

Ahrefs

Coinbase

Links

​Overview

​Authentication

​OAuth2 Authentication

​Required Credentials

​OAuth Configuration

​Available Actions

​Parameters

​Response

​Parameters

​Response

​Parameters

​Response

​Parameters

​Response

​Parameters

​Response

​Parameters

​Response

​Parameters

​Response

​Parameters

​Response

​Response

​Parameters

​Response

​Limits & Quotas

​Related integrations

PostGrid

Ahrefs

Coinbase

​Links

Overview

Authentication

OAuth2 Authentication

Required Credentials

OAuth Configuration

Available Actions

Parameters

Response

Parameters

Response

Parameters

Response

Parameters

Response

Parameters

Response

Parameters

Response

Parameters

Response

Parameters

Response

Response

Parameters

Response

Limits & Quotas

Related integrations

Links