Analyze Search Terms

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.

📊 AFTER calling this tool, help the user understand:

Opportunity Keywords:

What it means: These are winning search terms you’re missing
Profit potential: Shows expected additional profit if added
Suggested action: Add as new keywords with recommended bid and match type
Priority: Start with highest opportunity_value (profit potential)

Example: Search term: “enterprise security software pricing”

8 conversions, $240 cost,$ 4,800 value
Opportunity Value: $4,560 profit potential
Suggested Bid: $6.00 (based on current CPC and ROAS)
Suggested Match Type: EXACT (high intent, proven converter)
Action: Add this as an Exact match keyword with $6 bid

Negative Keywords:

What it means: These queries waste money and never convert
Cost: Total wasted spend on non-converting terms
Common patterns: “free”, “download”, “crack”, “review”, “how to”
Action: Add as negative keywords (campaign or account level)

Example: Search term: “free security software”

120 clicks, $540 wasted, 0 conversions
Reason: Low purchase intent (free)
Action: Add “free” as negative keyword at campaign level

Match Type Performance:

Exact: Tightest control, lowest waste, highest ROAS (recommended)
Phrase: Moderate flexibility, some waste, decent ROAS
Broad: Most volume, highest waste, lowest ROAS (use sparingly)

Example Analysis:

Exact: 450 keywords, ROAS 4.8x, 2% wasted spend ✅
Phrase: 280 keywords, ROAS 3.2x, 8% wasted spend ⚠️
Broad: 120 keywords, ROAS 1.8x, 45% wasted spend 🔴

Quick Actions:

Add top 5 opportunity keywords as Exact match
Block top 10 negative keywords at campaign level
Convert high-performing Broad keywords to Exact
Review Phrase keywords with >10% wasted spend

Visualization Tip: For opportunity keywords, suggest creating a scatter plot (x=ROAS, y=Spend, size=conversions) to visualize profit potential.

Implementation Steps:

Review top opportunities and negatives
Start with 5-10 new keywords (don’t overwhelm account)
Add negatives in batches (test impact over 7 days)
Convert Broad→Exact gradually (monitor volume drop)
Re-run analysis monthly to discover new opportunities

Best Practices:

Focus on opportunity_value (profit) not just ROAS
Start with Exact match for all new keywords (tightest control)
Add negatives at campaign level first (easier to undo than account level)
Monitor match type distribution: Aim for 60%+ Exact, 30% Phrase, 10% Broad
Review search terms every 2 weeks during active optimization

💬 Community: For keyword optimization discussions, visit our Discord: https://discord.gg/dH3Qt4YS

POST

api

tools

analyze_search_terms

execute

Analyze Search Terms

curl --request POST \
  --url https://api.adspirer.ai/api/v1/tools/analyze_search_terms/execute \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "arguments": {
    "analysis_type": "all",
    "date_range": "string",
    "end_date": "string",
    "lookback_days": 30,
    "raw_data": false,
    "start_date": "string"
  }
}
'

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

Authorizations

Authorization

string

header

required

API key from https://adspirer.ai/keys. Prefix sk_live_. Treat as a secret — never commit.

Headers

Idempotency-Key

string<uuid>

Client-generated UUID to make writes idempotent. Strongly recommended for write tools. A repeat call with the same key returns the cached result instead of re-executing. Example: 550e8400-e29b-41d4-a716-446655440000

Body

application/json

All tool arguments are wrapped in an arguments object. The fields accepted inside arguments are listed below — required fields are marked with a red asterisk.

arguments

object

required

Input schema for search term mining and keyword opportunity analysis

Show child attributes

Response

Tool executed successfully. data.text carries the human-readable result (markdown-friendly). data.quota shows your current usage against the plan limit. data.structured appears when the tool emits machine-parseable structured content. data.content appears for tools that return non-text blocks (images, resources).

Returned on HTTP 200. data.text is the primary human-readable output. data.quota is always present for billable calls. data.structured is set only when the tool emits machine-parseable structured content. data.content is set only when the tool emits non-text content blocks.

data

object

required

Show child attributes

success

boolean

required

tool

string

required

Echoed tool_name from the request URL.

Last modified on April 23, 2026

Analyze Wasted SpendAnalyze wasted ad spend and identify campaigns losing money or underperforming. ⚠️ IMPORTANT: This tool retrieves READ-ONLY data. Safe to call multiple times. 🎯 **What This Tool Does (Performance Agent - Phase 1):** - Identifies campaigns LOSING money (ROAS `<` 1.0x) - Identifies campaigns UNDERPERFORMING (1.0x ≤ ROAS `<` target) - Separates true waste from opportunity cost - Provides severity-based classification (CRITICAL/HIGH/MEDIUM) - Generates actionable recommendations with expected impact - Shows top performing campaigns for budget reallocation **Returns detailed analysis:** - Total wasted spend (campaigns with ROAS `<` 1.0) - Total underperforming spend (profitable but below target) - Campaign-by-campaign breakdown with severity levels - Specific recommendations (PAUSE/REDUCE/OPTIMIZE) - Quick actions for immediate implementation - Budget reallocation suggestions **Target ROAS Resolution (3-tier priority):** 1. Account goals table (user-set or API-pulled) 2. 90-day historical average ROAS 3. Default to 2.0x if no data available **Severity Levels:** - 🚨 CRITICAL: ROAS `<` 0.5x (losing money severely) - 🔴 HIGH: ROAS `<` 1.0x (unprofitable/breakeven) - 🟡 MEDIUM: 1.0x ≤ ROAS `<` target (profitable but underperforming) **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. - target_roas: Optional override (e.g., 3.0 for 3.0x ROAS) - customer_id: Optional (uses connected account if omitted) **Execution time:** 1-3 seconds (cached database query) **Data source:** campaign_daily_metrics table (updated nightly) **Use this tool when:** - User asks "where is my money going?" - User wants to identify wasted spend - User wants to optimize campaign budgets - User asks which campaigns to pause/reduce - User wants to know which campaigns are losing money 📊 **AFTER calling this tool, help the user understand:** **Wasted vs. Underperforming:** - **Wasted Spend** = Actual losses (ROAS `<` 1.0, you're losing money) - **Underperforming Spend** = Opportunity cost (profitable but below target) **Example:** - Campaign A: Spent $1000, got $600 back (ROAS 0.6x) → $400 WASTED - Campaign B: Spent $1000, got $1500 back (ROAS 1.5x, target 3.0x) → $0 wasted, but $500 opportunity cost **Quick Actions (IMPORTANT — read severity context first):** - ⏳ LEARNING campaigns → Do NOT pause. Monitor for 14+ days before judging. - ❓ INSUFFICIENT_DATA campaigns → Need more spend before analysis is meaningful. - 🚨 CRITICAL campaigns (established, 14+ days, ZERO conversions) → Consider pausing - 🚨 CRITICAL campaigns (established, 14+ days, HAS conversions) → Review performance, verify revenue in ad platform before reducing budget - 🔴 HIGH severity (established, 14+ days) → Consider reducing budget by 50-70% - 🟡 MEDIUM → Optimize targeting, ad copy, landing pages - Top performers → Consider increasing budget ⚠️ **NEVER say "pause" for a campaign that has conversions.** Say "review" or "reduce budget" instead. ⚠️ **NEVER recommend pausing a campaign in LEARNING phase.** ⚠️ **If ALL campaigns are LEARNING or INSUFFICIENT_DATA, tell the user their account is too new for waste analysis and recommend checking back in 2 weeks.** ⚠️ **Consider campaign objective: brand awareness campaigns will not have ROAS data. This is normal.** ⚠️ **When data confidence is MEDIUM or LOW, soften all recommendations and add verification prompts.** **Visualization Tip:** For 10+ campaigns, suggest creating a treemap visualization to show wasted spend by campaign size. 💬 **Community**: For optimization discussions, visit our Discord: https://discord.gg/dH3Qt4YS

Analyze Search Terms

curl --request POST \
  --url https://api.adspirer.ai/api/v1/tools/analyze_search_terms/execute \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "arguments": {
    "analysis_type": "all",
    "date_range": "string",
    "end_date": "string",
    "lookback_days": 30,
    "raw_data": false,
    "start_date": "string"
  }
}
'

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