add_keywords

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

🚨 **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 keywords to an existing ad group. ⚠️ **CRITICAL: Run `research_keywords` BEFORE using this tool!** **MANDATORY WORKFLOW:** 1. Call `get_campaign_structure` to get ad_group_id and see existing keywords 2. Call `research_keywords` with business context to get quality keyword suggestions 3. Show keyword suggestions to user with CPC, search volume, intent level 4. Get user approval on which keywords to add 5. ONLY THEN call this tool with approved keywords **Why research first?** - Ensures keywords have real search volume - Shows CPC costs so user understands budget impact - Provides HIGH/MEDIUM/LOW intent classification - Prevents adding low-quality or irrelevant keywords **Requires:** - ad_group_id: Get from get_campaign_structure (REQUIRED) - keywords: List of keywords to add (from research_keywords results) **Each keyword needs:** - text: The keyword phrase (e.g., "buy running shoes online") - match_type: EXACT, PHRASE, or BROAD (default: BROAD) - cpc_bid_micros: Optional bid override (1 USD = 1,000,000 micros) **Match Type Guide:** - BROAD: Ads show for related searches (widest reach) - Google's 2025 recommendation - PHRASE: Ads show when query contains keyword phrase - EXACT: Ads show only for exact query or close variants **IMPORTANT:** - Keyword text and match_type CANNOT be changed after creation - To "change" a keyword, remove the old one and add a new one - Get ad_group_id from get_campaign_structure first **Execution time:** 2-4 seconds **Example Workflow:** User: "Add more keywords to my plumbing campaign" Agent Steps: 1. Call get_campaign_structure → get ad_group_id, see existing keywords 2. Call research_keywords with business_description="plumbing services" 3. Show user: "I found these keyword suggestions from Keyword Planner: - emergency plumber near me (HIGH intent, $45 CPC, 12K searches/mo) - 24 hour plumber (HIGH intent, $38 CPC, 8K searches/mo) Which would you like to add?" 4. User selects keywords 5. Call add_keywords with selected keywords

{
  "arguments": {
    "ad_group_id": "string",
    "keywords": [
      {
        "text": "running shoes",
        "match_type": "PHRASE",
        "cpc_bid_micros": 500000
      },
      {
        "text": "nike air max",
        "match_type": "EXACT"
      }
    ],
    "customer_id": "string"
  }
}

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

{
  "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_keywords"
}

{
  "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_keywords",
  "quota": {
    "used": 150,
    "limit": 150,
    "tier": "plus",
    "period_end": "2026-05-01",
    "upgrade_url": "https://adspirer.ai"
  }
}