analyze_search_terms

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

Discover keyword opportunities and optimize match types by analyzing actual search terms. ⚠️ IMPORTANT: This tool retrieves READ-ONLY data. Safe to call multiple times. Google Ads only - NOT available for TikTok. 🎯 **What This Tool Does (Performance Agent - Phase 1 Feature 3):** - Identifies OPPORTUNITY keywords: Converting search terms NOT in your keyword list - Identifies NEGATIVE keywords: Expensive terms with zero conversions - Analyzes MATCH TYPE performance: Exact vs Phrase vs Broad efficiency - Provides specific recommendations with suggested bids and match types - Ranks opportunities by profit potential (not just ROAS) **Returns comprehensive keyword intelligence:** - Top 20 opportunity keywords with suggested bids and match types - Top 20 negative keyword candidates with wasted cost breakdown - Match type performance comparison (Exact/Phrase/Broad) - Broad→Exact conversion recommendations - Total opportunity value and wasted spend amounts - Actionable recommendations for immediate implementation 🔍 **What Search Term Mining Reveals:** **Opportunity Keywords (Money Left on Table):** - Search terms that ARE converting but you're NOT bidding on them directly - These are queries triggering your ads via Broad/Phrase match, but should be added as Exact keywords - Example: User searches "enterprise security software pricing" → converts → but you only have "security software" as keyword - **Action:** Add high-converting search terms as new keywords with suggested bids **Negative Keywords (Money Wasted):** - Search terms costing >$10 with ZERO conversions - Low-intent queries like "free", "download", "crack", "how to" - Example: "free security software download" → 120 clicks, $540 spent, 0 conversions - **Action:** Add as negative keywords to stop wasting budget **Match Type Optimization:** - Compares performance of Exact vs Phrase vs Broad match - Identifies Broad keywords that should be converted to Exact for better control - Example: Broad "security software" has 45% wasted spend, but top search terms have 20x ROAS - **Action:** Convert high-performing Broad keywords to Exact match **Parameters:** - lookback_days: 7, 30, 60, 90, or 120 days (default: 30) - start_date: Optional start date (YYYY-MM-DD). Overrides lookback_days when used with end_date. - end_date: Optional end date (YYYY-MM-DD). Overrides lookback_days when used with start_date. ⚠️ DATE CLARIFICATION: If the user's date request is vague or ambiguous (e.g., "March to June" without a year, "last quarter", "recently", "a few months ago"), ask the user to specify exact dates before calling this tool. Do not assume or guess dates. - analysis_type: 'opportunities', 'negatives', 'match_types', 'all', or **'raw_report'** (default: 'all') - Use **'raw_report'** when the user wants to SEE their actual search terms — the words customers type into Google - force_refresh: true to trigger immediate API collection (default: false, uses cached data) - customer_id: Optional (uses connected account if omitted) - **campaign_id**: Optional — filter search terms to a specific campaign (get from list_campaigns) - **page**: Page number for raw_report pagination (default: 1) - **page_size**: Results per page for raw_report (1-100, default: 50) - **sort_by**: Sort for raw_report: 'cost' (default), 'clicks', 'impressions', 'conversions' - **min_clicks**: Minimum clicks filter for raw_report (default: 0) **Execution time:** 1-3 seconds (cached database query) **Data source:** search_term_daily_metrics table (updated nightly, 120-day retention) **⚡ RAW REPORT PAGINATION CONTRACT:** - When using analysis_type='raw_report', results are paginated - Check `pagination.has_more` — if true, call again with next `page` - Continue until `has_more` is false, then present consolidated results - Use `campaign_id` to focus on a specific campaign's search terms **Use this tool when:** - User asks "what keywords should I add?" - User wants to find wasted spend at keyword level - User asks "what should I add as negative keywords?" - User wants to improve match type efficiency - User asks "which Broad keywords should be Exact?" - User wants to discover hidden keyword opportunities - **User asks "show me my search terms" or "what are people searching for?"** → use analysis_type='raw_report' - **User asks "show me search terms for campaign X"** → use analysis_type='raw_report' with campaign_id ⚠️ **Platform Limitation:** This tool ONLY works for Google Ads. TikTok Ads does not provide search term data due to privacy restrictions.

{
  "arguments": {
    "start_date": "string",
    "end_date": "string",
    "date_range": "string",
    "raw_data": false,
    "lookback_days": 30,
    "analysis_type": "all"
  }
}

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

{
  "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": "analyze_search_terms"
}

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