zuckerbot_get_campaign_insights
Query campaign, ad set, or ad-level performance for any Meta ad campaign, with date range, status, and name filters. Tags rows to benchmark automated campaigns against manually managed ones.
Instructions
Query campaign, ad set, or ad-level performance for any campaign in the connected Meta ad account — including campaigns not created by ZuckerBot. Tags each row with is_zuckerbot so you can benchmark ZuckerBot campaigns against manually managed ones. Supports date range filtering, campaign name search, status filters, time-series breakdowns, and multi-column sorting. For deduped truth use meta_result / cost_per_meta_result (Meta's Ads Manager "Results" for any objective) or conversion_leads / meta_leads — not the inflated, deprecated leads / cpl (the response's metric_semantics object labels every lead field). meta_result and conversion_leads are most reliable on campaign-level, non-time-incremented queries. Adset/ad rows report their OWN status — status_scope says which entity a row's status belongs to, statuses are as of status_synced_at, and refresh=true re-syncs them; spend-by-date is authoritative for whether delivery actually happened.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| sort | No | Optional sort field. Plain values sort descending; prefix with '+' for ascending. One of: spend, leads, cpl, meta_leads, conversion_leads, cpcl, meta_result, cpmr, results, cpr, ctr, impressions. Prefer meta_result / cpmr (Meta's deduped 'Results' for any objective) or conversion_leads / meta_leads over the deprecated, inflated leads / cpl. | |
| level | No | Return campaign totals, ad set breakdowns, or ad breakdowns | |
| limit | No | Maximum campaigns to return after sorting | |
| search | No | Optional case-insensitive campaign name substring filter | |
| status | No | Optional status filter. Use active, paused, or all for the simple path, or pass legacy comma-separated values such as ACTIVE,PAUSED. | |
| date_to | No | Optional end date in YYYY-MM-DD format. Defaults to today. | |
| refresh | No | Bypass the short-lived performance cache | |
| date_from | No | Optional start date in YYYY-MM-DD format. Defaults to 7 days ago. | |
| business_id | No | Optional business ID override linked to the connected Meta ad account | |
| campaign_ids | No | Optional comma-separated Meta campaign IDs | |
| time_increment | No | Optional daily or monthly time-series breakdown |