create_conversion_action

POST https://api.adspirer.ai/api/v1/tools/create_conversion_action/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 Create a WEBPAGE conversion action so the account can use TARGET_CPA / MAXIMIZE_CONVERSIONS / TARGET_ROAS bidding. **Why this matters:** Without conversion actions, Smart Bidding strategies (TARGET_CPA, MAXIMIZE_CONVERSIONS, TARGET_ROAS) can't function correctly. They need a "what counts as a conversion" definition to optimize toward. This tool creates that definition. **v1 scope:** WEBPAGE conversion actions only. After creating, the customer must: 1. Install the Google site tag (gtag.js) on their website if not already present 2. Add an event snippet on the conversion page (or fire it on a click/form submit) 3. Wait 24-48 hours for the first conversions to flow in 4. THEN apply TARGET_CPA bidding (it needs a few conversions to optimize) Phone-call / app / Firebase / Floodlight conversion types are deferred to a future tool. **Pick the right category:** - E-commerce purchase → PURCHASE (set value + currency) - Lead-gen form submit → SUBMIT_LEAD_FORM (set value if leads have known $ worth) - Newsletter signup / account creation → SIGNUP - Add-to-cart tracking → ADD_TO_CART - Begin-checkout (abandonment funnel) → BEGIN_CHECKOUT - Phone-call lead from ad → PHONE_CALL_LEAD - Outbound click on partner site → OUTBOUND_CLICK - Engagement metric (page time, scroll, video play) → ENGAGEMENT - "Get directions" tap on a map ad → GET_DIRECTIONS - Quote request → REQUEST_QUOTE - Appointment booked → BOOK_APPOINTMENT - Generic contact form → CONTACT - Use DEFAULT only if none fit. **Counting type:** - ONE_PER_CLICK (default): one conversion per ad click. Use for lead-gen, signups, downloads. - MANY_PER_CLICK: every purchase counts, even multiple from same click. Use for e-commerce. **Value settings:** - Recommended for lead-gen: set `value` to your average lead $ worth (e.g. 50.0 for $50/lead). This gives TARGET_CPA something to optimize. - Set `always_use_default_value=true` if every conversion has the same value (lead-gen). - Leave both unset for e-commerce — the tag sends actual transaction values. **Example:** User: "Set up TARGET_CPA bidding for my lead-gen campaign" Agent: 1. Calls create_conversion_action(name="Lead Form Submit", category="SUBMIT_LEAD_FORM", value=50.0, always_use_default_value=true) 2. Tells user: "Created the conversion goal. Now install the Google tag on your thank-you page, then I'll switch the campaign to TARGET_CPA." 3. After tag is installed and conversions are flowing, calls update_bid_strategy(strategy="TARGET_CPA", target_cpa=20.0).

{
  "arguments": {
    "name": "string",
    "category": "string",
    "value": 1.0,
    "currency_code": "string",
    "always_use_default_value": false,
    "counting_type": "ONE_PER_CLICK",
    "click_through_lookback_window_days": 30,
    "view_through_lookback_window_days": 1
  }
}

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

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

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