API Reference › Google Ads › add_demandgen_ad_group

add_demandgen_ad_group

Google Ads Write

🚨 **IF THIS TOOL RETURNS A QUOTA ERROR:** - The error message will include a clickable upgrade link - Show the FULL error message to the user (it contains the upgrade link) - DO NOT attempt to work ar

Endpoint

POST https://api.adspirer.ai/api/v1/tools/add_demandgen_ad_group/execute

Headers

Description

🚨 **IF THIS TOOL RETURNS A QUOTA ERROR:** - The error message will include a clickable upgrade link - Show the FULL error message to the user (it contains the upgrade link) - DO NOT attempt to work around the error or use alternative data - DO NOT create campaigns or perform actions without valid tool data - STOP and direct the user to upgrade via the provided link Add a new ad group with targeting and ads to an EXISTING Demand Gen campaign. Use this after create_demandgen_campaign to add additional ad groups. Each ad group can have: - **Different location targeting** (e.g., US cities vs India cities vs UAE cities) - **Different audience targeting** (e.g., marketing pros vs tech founders vs agency owners) - **Same or different ad creative** (headlines, descriptions, images, videos) **Reuse Existing Audiences:** To attach an existing audience (from Google Ads UI or a previous campaign), pass: - audience_segments.existing_audience_id: numeric audience ID - audience_segments.existing_audience_resource_name: full resource name **Create New Audiences:** To create a new audience from interest segments: - audience_segments.in_market_audience_ids: [80517, 80520] - audience_segments.affinity_audience_ids: [92948] Use search_audiences to find segment IDs. **Parameters:** - campaign_id: Demand Gen campaign ID (from create_demandgen_campaign or list_campaigns) - ad_group_name: Descriptive name - Same creative fields as create_demandgen_campaign (headlines, descriptions, images, etc.) - target_locations: Location targeting specific to this ad group - audience_segments: Audience targeting specific to this ad group **Execution time:** 10-20 seconds

Request body

All tool arguments are wrapped in an arguments object.

FieldTypeDescription
campaign_idstring requiredThe Demand Gen campaign ID to add the ad group to. Get from list_campaigns or get_campaign_structure.
ad_group_namestring requiredName for the new ad group (e.g., 'US Metro - Marketing Pros')
ad_formatstring optionalAd format: 'multi_asset' (image ads, default), 'video_responsive' (video ads). default: "multi_asset"
final_urlstring requiredLanding page URL. Example: 'https://example.com/product'
business_namestring requiredBusiness name, max 25 characters.
headlinesarray requiredMUST BE JSON ARRAY: 1-5 headlines, each max 40 characters.
descriptionsarray requiredMUST BE JSON ARRAY: 1-5 descriptions, each max 90 characters.
long_headlinesarray optionalOptional 1-5 long headlines, max 90 chars each. For video_responsive format.
call_to_actionstring optionalCTA label: LEARN_MORE, SHOP_NOW, SIGN_UP, SUBSCRIBE, DOWNLOAD, BOOK_NOW, etc.
target_locationsarray optionalGeographic targets for THIS ad group (e.g., ['New York', 'Bangalore']). Each ad group can target different locations.
target_languagesarray optionalLanguage targets as ISO codes (e.g., ['en']). Defaults to English.
channelsobject optionalOptional channel controls for this ad group.
marketing_imagesarray optionalLandscape images (1.91:1) as [{"url": "...", "name": "img1"}].
square_marketing_imagesarray optionalSquare images (1:1) as [{"url": "...", "name": "img1"}].
portrait_marketing_imagesarray optionalPortrait images (4:5) as [{"url": "...", "name": "img1"}].
existing_imagesobject optionalExisting image asset resource names to reuse. Keys: marketing_images_landscape, marketing_images_square, marketing_images_portrait, logos_square.
youtube_video_idsarray optionalYouTube video IDs for video_responsive format. 1-5 videos.
logo_asset_idstring optionalLogo image asset ID from discover_existing_assets.
logo_imagesarray optionalNew logo images as [{"url": "...", "name": "logo1"}].
asset_bundle_idstring optionalAsset bundle ID from validate_and_prepare_assets.
audience_segmentsobject optionalAudience targeting for THIS ad group. CRITICAL: Only use segment IDs returned by search_audiences tool. NEVER fabricate or guess IDs -- wrong IDs target unrelated audiences and waste budget. If search_audiences returns no results, skip audience_segments entirely. To REUSE an existing audience: {'existing_audience_id': 12345} or {'existing_audience_resource_name': 'customers/123/audiences/456'}. To CREATE new: {'in_market_audience_ids': [80463], 'affinity_audience_ids': [92913], 'custom_audience_ids': ['customers/123/customAudiences/456']}. Use search_audiences to find segment IDs.
customer_idstring optionalGoogle Ads customer ID. Required for multi-account users. Get from list_connected_accounts.

Example request

{
  "arguments": {
    "campaign_id": "<campaign_id>",
    "ad_group_name": "string",
    "final_url": "https://example.com",
    "business_name": "string",
    "headlines": [
      "string"
    ],
    "descriptions": [
      "string"
    ],
    "ad_format": "multi_asset",
    "long_headlines": [
      "string"
    ],
    "call_to_action": "string",
    "target_locations": [
      "string"
    ],
    "target_languages": [
      "string"
    ],
    "channels": [
      "YOUTUBE",
      "DISCOVER",
      "GMAIL"
    ]
  }
}

Example responses

200 — Success

{
  "success": true,
  "data": {
    "text": "(tool-specific textual output for add_demandgen_ad_group)",
    "quota": {
      "used": 42,
      "limit": 150,
      "tier": "plus",
      "period_end": "2026-05-01"
    }
  },
  "tool": "add_demandgen_ad_group"
}

400 — Tool-level error (bad arguments / multi-account selection)

{
  "success": false,
  "error": "You have 25 meta_ads accounts connected. Please specify which account to use by passing the ad_account_id parameter:\n  - Acme Holdings (ad_account_id=\"act_123456789\")\n  - Acme EU (ad_account_id=\"act_987654321\")",
  "is_error": true,
  "tool": "add_demandgen_ad_group"
}

402 — Quota exhausted

{
  "success": false,
  "error": "\ud83d\udea8 Monthly limit reached (150/150 tool calls on Plus tier).\nUpgrade to Pro at https://adspirer.ai to keep building.",
  "is_error": true,
  "tool": "add_demandgen_ad_group",
  "quota": {
    "used": 150,
    "limit": 150,
    "tier": "plus",
    "period_end": "2026-05-01",
    "upgrade_url": "https://adspirer.ai"
  }
}

Try it live

Interactive: Swagger UI

Machine-readable: OpenAPI 3.1 spec · llms-full.txt

More tools: Google Ads · All tools

Adspirer REST API — get an API key at adspirer.ai/keys · adspirer.ai