Get Campaign Performance

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

POST

/

api

/

v1

/

tools

/

get_campaign_performance

/

execute

Get Campaign Performance

curl --request POST \
  --url https://api.adspirer.ai/api/v1/tools/get_campaign_performance/execute \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "arguments": {
    "customer_id": "string",
    "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 get_campaign_performance)"
  },
  "success": true,
  "tool": "get_campaign_performance"
}

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

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

Get Campaign StructureGet campaign structure with ad groups, keywords, ads, and extensions. Supports pagination for large campaigns. This tool retrieves READ-ONLY data. Safe to call multiple times. **Returns campaign hierarchy (paginated by ad groups):** - Campaign details (name, status, budget, bidding strategy) - Ad groups with their settings (paginated — default 5 per page) - Keywords per ad group (including match types, bids, status) - Ads per ad group (including RSA headlines/descriptions, ad strength) - Negative keywords per ad group - Campaign-level extensions and negative keywords (on page 1 only) - Pagination metadata (page, total_pages, has_more) - Summary counts (total ad groups, keywords, ads across ALL pages) **Parameters:** - campaign_id: The campaign ID (REQUIRED - get from list_campaigns) - customer_id: Optional (uses connected account if omitted) - page: Page number, 1-based (default: 1) - page_size: Ad groups per page, 1-50 (default: 5) - ad_group_id: Optional — fetch only this single ad group (bypasses pagination) - include: What detail per ad group: 'all' (default), 'summary' (counts only), 'keywords', 'ads' **⚡ PAGINATION CONTRACT (IMPORTANT FOR AI AGENTS):** - The response includes `pagination.has_more` — if true, you MUST call again with `page` incremented - Continue calling until `has_more` is false - Then consolidate all pages and present the complete campaign structure to the user - The `summary` section is always included and shows total counts across ALL ad groups (not just the current page) - Extensions and campaign-level negative keywords are only returned on page 1 - Use `ad_group_id` to drill into a single ad group when the user asks about a specific one - Use `include='summary'` for a quick overview without nested keyword/ad data **Execution time:** 3-8 seconds per page (multiple API queries) **Use this tool when:** - User wants to update an existing campaign - User wants to see current keywords/ads - User wants to add extensions to existing campaign - User says "show me what's in this campaign" - Before making any updates to a campaign **Important IDs returned:** - campaign.id - For campaign-level updates (budget, status) - ad_groups[].id - For adding keywords/ads - keywords[].id - For keyword updates (status, bids) - ads[].id - For ad content updates **Example flow:** 1. User: "I want to update my campaign" 2. Agent: Uses list_campaigns to show all campaigns 3. User: Selects campaign "Summer Sale 2025" 4. Agent: Uses get_campaign_structure with that campaign_id 5. If has_more=true, agent calls again with page=2, page=3, etc. 6. Agent: Shows consolidated structure and asks what to update 7. User: "Change the headlines" 8. Agent: Uses update_ad_headlines with the ad_id from structure

Get Campaign Performance

curl --request POST \
  --url https://api.adspirer.ai/api/v1/tools/get_campaign_performance/execute \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "arguments": {
    "customer_id": "string",
    "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 get_campaign_performance)"
  },
  "success": true,
  "tool": "get_campaign_performance"
}