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
POST https://api.adspirer.ai/api/v1/tools/add_search_ad_group/execute
Authorization: Bearer sk_live_... — your Adspirer API key (required)Content-Type: application/json (required)Idempotency-Key: <uuid> — recommended for write operations to make retries safeAll tool arguments are wrapped in an arguments object.
| Field | Type | Description |
|---|---|---|
campaign_id | string required | Existing Search campaign ID (from list_campaigns). |
ad_group_name | string required | Name for the new ad group. |
cpc_bid_micros | integer optional | Optional max CPC bid in micros (1_000_000 = 1 unit of account currency). Only used when the campaign bidding strategy allows a manual/ad-group bid. |
target_cpa_micros | integer optional | Optional ad-group target CPA in micros. |
keywords | array optional | Optional keywords to seed the ad group (plain text). Run research_keywords first for ideas. |
headlines | array optional | Optional RSA headlines to create an ad in this group (each ≤30 chars). Requires descriptions + final_url too. ⚠️ Provide 10+ real headlines: Google pads to 10 and any shortfall is filled with generic 'Default Headline N' placeholders that go LIVE. Aim for 10-15. |
descriptions | array optional | Optional RSA descriptions (each ≤90 chars). Requires headlines + final_url too. ⚠️ Provide 4 real descriptions: shortfalls are padded with generic 'Default Description N' placeholders that go LIVE. Aim for 4. |
final_url | string optional | Landing page URL for the seeded RSA (required if headlines set). |
customer_id | string optional | Google Ads customer ID. Required for multi-account users. |
{
"arguments": {
"campaign_id": "<campaign_id>",
"ad_group_name": "string",
"cpc_bid_micros": 1,
"target_cpa_micros": 1,
"keywords": [
"string"
],
"headlines": [
"string"
],
"descriptions": [
"string"
],
"final_url": "string"
}
}
{
"success": true,
"data": {
"text": "(tool-specific textual output for add_search_ad_group)",
"quota": {
"used": 42,
"limit": 150,
"tier": "plus",
"period_end": "2026-05-01"
}
},
"tool": "add_search_ad_group"
}
{
"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_search_ad_group"
}
{
"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_search_ad_group",
"quota": {
"used": 150,
"limit": 150,
"tier": "plus",
"period_end": "2026-05-01",
"upgrade_url": "https://adspirer.ai"
}
}
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