get_campaign_performance

POST https://api.adspirer.ai/api/v1/tools/get_campaign_performance/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 Analyze Google Ads campaign performance with comprehensive insights and recommendations. ⚠️ IMPORTANT: This tool retrieves READ-ONLY data. Safe to call multiple times. **Returns detailed analysis:** - Campaign structure and ad group organization - Keyword performance with quality scores and match types - Ad group performance breakdown - Performance metrics (CTR, conversions, CPC, cost, ROAS) - Optimization recommendations with actionable insights - Performance trends (last 7 days) **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. - customer_id: Optional (uses connected account if omitted) **Execution time:** 2-5 seconds (direct backend API call) **Data source:** Cached database (updated nightly via metrics collection) **Use this tool to:** - Review current campaign performance - Identify optimization opportunities - Get data-driven recommendations - Analyze keyword and ad effectiveness - Understand what's working and what needs improvement 📊 **AFTER calling this tool, provide these insights to the user:** **How to Interpret Metrics:** - **CTR (Click-Through Rate):** Industry average is 3-5% for search ads - Above 5%: Excellent ad relevance - Below 2%: Consider improving ad copy or targeting - **Conversion Rate:** Industry average is 2-5% - Low CR + High CTR = Landing page issue - Low CR + Low CTR = Ad/targeting issue - **CPA (Cost Per Acquisition):** Compare to your target CPA - Track the trend over time - Adjust bids if CPA is consistently too high 💡 **Optimization Tips:** - Wait at least 2 weeks before making major changes (learning phase) - Focus on high-performing keywords and pause low performers - Test different ad copy variations (A/B testing) - Adjust bids based on device/location performance - Review search terms report for negative keyword opportunities 💬 **Community**: For optimization discussions and tips, visit our Discord: https://discord.gg/dH3Qt4YS

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

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

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

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