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

account_id

string

required

user_list_id

string

required

ID of the CRM-based customer list to update.

contact_email

string

required

Email address of the contact to add.

customer_client_id

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

account_id

string

required

fields

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.

segments

array

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

metrics

array

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

object_filter

array

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

date_range

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.

start_date

string

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

end_date

string

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

order_by

string

Field name to order results by.

direction

string

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

limit

integer

Maximum number of results to return.

customer_client_id

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

account_id

string

required

fields

array

List of ad_group_ad fields to select (strings).

segments

array

List of segments (strings).

metrics

array

List of metric fields (strings).

object_filter

array

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

date_range

string

Date range constant. See create_ad_group_report for valid values.

start_date

string

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

end_date

string

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

order_by

string

Field name to order results by.

direction

string

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

limit

integer

Maximum number of results to return.

customer_client_id

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

account_id

string

required

fields

array

List of campaign fields to select (strings).

segments

array

List of segments (strings).

metrics

array

List of metric fields (strings).

object_filter

array

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

date_range

string

Date range constant. See create_ad_group_report for valid values.

start_date

string

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

end_date

string

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

order_by

string

Field name to order results by.

direction

string

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

limit

integer

Maximum number of results to return.

customer_client_id

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

account_id

string

required

name

string

required

Name of the user list.

list_type

string

required

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

list_type_data

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: {})

description

string

Optional description of the user list.

additional_fields

object

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

customer_client_id

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

account_id

string

required

fields

array

List of customer fields to select (strings).

segments

array

List of segments (strings).

metrics

array

List of metric fields (strings).

object_filter

array

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

date_range

string

Date range constant. See create_ad_group_report for valid values.

start_date

string

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

end_date

string

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

order_by

string

Field name to order results by.

direction

string

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

limit

integer

Maximum number of results to return.

customer_client_id

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

account_id

string

required

resource

string

required

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

fields

array

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

segments

array

List of segments (strings).

metrics

array

List of metric fields (strings).

object_filter

array

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

date_range

string

Date range constant. See create_ad_group_report for valid values.

start_date

string

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

end_date

string

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

order_by

string

Field name to order results by.

direction

string

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

limit

integer

Maximum number of results to return.

customer_client_id

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

account_id

string

required

customer_client_id

string

required

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

additional_fields

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

account_id

string

required

name

string

required

Name of the conversion action.

type

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.

additional_fields

object

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

customer_client_id

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.

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