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/create_search_campaign/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_name | string required | Campaign name (e.g., 'Luxury Watches Q4 2025') |
business_description | string required | REQUIRED. What the business sells/does, in one sentence — used to generate ad copy and keyword themes. Example: 'Luxury watch retailer specializing in pre-owned Rolex and Omega'. If the user hasn't told you, ask them or infer it from the website before calling. |
website_url | string required | REQUIRED. The landing-page URL ads send clicks to. Example: 'https://example.com' or 'https://example.com/watches'. Use the user's site; if unknown, ask — do not omit this field. |
budget_daily | number required | REQUIRED. Daily budget in the account's native currency. Example: 50 for $50/day, or 1000 if the user says '₹1000/day'. Do NOT convert currencies — pass the user's amount as-is; the Google Ads API interprets it in the account's currency. Google recommends ~$10/day USD min for Search. If the user hasn't given a budget, ask for one — do not guess or omit. |
target_locations | array required | REQUIRED. Geographic targets as a JSON array of strings — countries, states, cities, or regions. Examples: ['India'], ['Mumbai, India'], ['New York, NY'], ['United States', 'Canada']. Always provide at least one; if the user didn't specify, ask where they want ads shown. |
ad_groups | array required | REQUIRED. One or more themed ad groups (2-5 is typical; more is allowed for a fuller structure), each with keywords, headlines, and descriptions. Each ad group is one theme/audience segment, and can carry up to 3 distinct RSAs via `additional_ads`. Example: [{'name': 'Rolex Watches', 'keywords': ['rolex for sale', 'buy rolex'], 'headlines': ['Authentic Pre-Owned Rolex', 'Certified Rolex Watches'], 'descriptions': ['Shop certified pre-owned Rolex with warranty.']}]. Run research_keywords first if you need keyword ideas. |
negative_keywords | array optional | Campaign-level negative keywords (optional, e.g., ['free', 'cheap', 'used']) |
bidding_strategy | string optional | Bidding strategy for the campaign. Options: 'MAXIMIZE_CONVERSIONS' (default) - Get the most conversions within budget. 'MAXIMIZE_CONVERSION_VALUE' - Optimize for highest value conversions (requires target_roas). Recommended: MAXIMIZE_CONVERSIONS for new campaigns. default: "MAXIMIZE_CONVERSIONS" |
objective | string optional | Campaign objective/goal. Options: 'CONVERSIONS' (default) - Track and optimize for sales, leads, or sign-ups. 'CLICKS' - Maximize website traffic. Recommended: CONVERSIONS for performance-focused campaigns. default: "CONVERSIONS" |
target_roas | number optional | Target ROAS (Return on Ad Spend) for MAXIMIZE_CONVERSION_VALUE bidding. Example: 3.0 means you want $3 revenue for every $1 spent. Only required when bidding_strategy='MAXIMIZE_CONVERSION_VALUE'. |
customer_id | string optional | Google Ads customer ID (10 digits, no dashes). REQUIRED whenever the user has more than one Google Ads account connected — this creates a REAL campaign that spends REAL money, so it must land in the account the user actually meant. Do NOT omit it and do NOT guess: carry over the customer_id already in use in this conversation, or call list_connected_accounts / get_connections_status and ask the user which account. If a call fails asking you to disambiguate, RETRY with this parameter — that error does NOT mean the account is disconnected. |
{
"arguments": {
"campaign_name": "string",
"business_description": "string",
"website_url": "https://example.com",
"budget_daily": 1.0,
"target_locations": [
"string"
],
"ad_groups": [
{
"name": "string",
"keywords": [
"string"
],
"headlines": [
"string"
],
"descriptions": [
"string"
],
"final_url": "https://example.com",
"sitelinks": [
{
"link_text": null,
"final_url": null,
"description1": null,
"description2": null
}
],
"audiences": {
"demographics": null,
"custom_audiences": null,
"in_market_audiences": null,
"affinity_audiences": null
},
"additional_ads": [
{
"headlines": null,
"descriptions": null,
"final_url": null
}
]
}
],
"negative_keywords": [
"string"
],
"bidding_strategy": "MAXIMIZE_CONVERSIONS",
"objective": "CONVERSIONS",
"target_roas": 1.0,
"customer_id": "string"
}
}
{
"success": true,
"data": {
"text": "(tool-specific textual output for create_search_campaign)",
"quota": {
"used": 42,
"limit": 150,
"tier": "plus",
"period_end": "2026-05-01"
}
},
"tool": "create_search_campaign"
}
{
"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": "create_search_campaign"
}
{
"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": "create_search_campaign",
"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