add_placement_exclusions

POST https://api.adspirer.ai/api/v1/tools/add_placement_exclusions/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 Exclude placements — add negative placement criteria so your ads STOP serving on specific websites, YouTube channels/videos, or apps. This is the write side that closes the optimization loop after `get_placement_performance` finds wasted or off-target placements. **What it does:** adds NEGATIVE placement criteria at the campaign level (applies to all ad groups) OR a single ad-group level. It is non-destructive — it does NOT pause or delete any campaign, ad group, ad, or existing targeting; it only prevents future serving on the placements you list. (To undo, the negative criterion can be removed later.) **Scope — provide exactly ONE:** - `campaign_id` — exclude across the whole campaign (all ad groups) - `ad_group_id` — exclude only within that ad group **Placements** — a list of `{type, value}`: - `WEBSITE` → value = domain/url (e.g. `msn.com`) - `YOUTUBE_CHANNEL` → value = channel id - `YOUTUBE_VIDEO` → value = video id - `MOBILE_APPLICATION` → value = app id Typically you take the `target_url` / `display_name` of placements that `get_placement_performance` shows with spend but zero conversions, and pass them here. **Returns:** which placements were `added` (with their criterion resource names) and which were `skipped` (invalid type/empty value), plus counts. Invalid rows are reported, never silently dropped. **Parameters:** - customer_id: Optional (uses connected account if omitted) - campaign_id OR ad_group_id: exactly one (required) - placements: list of {type, value} (required) **Use this tool when:** - User wants to exclude wasteful placements found via `get_placement_performance` - User says "block ads on <site>", "exclude this channel/app", "stop showing on these placements" **Tip:** Pair with `get_placement_performance` (`zero_conversions_only=true` + `min_cost`) to find the waste, then exclude it here in the same workflow.

{
  "arguments": {
    "placements": [
      {
        "type": "string",
        "value": "https://example.com"
      }
    ],
    "customer_id": "string",
    "campaign_id": "string",
    "ad_group_id": "string",
    "raw_data": false
  }
}

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

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

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