Meta-Ads-Kampagnen-Performance der letzten N Tage (je Zeile campaign_id +
campaign — die ID ist der Schlüssel für meta_update_campaign & Co.).
Zeitraum: heute minus N Tage bis heute EINSCHLIESSLICH (N+1 Kalendertage;
heute unvollständig). Für Vergleiche mit Google-Ads-Zahlen (schließen heute
aus) daily=True nutzen und den heutigen Tag herausrechnen.
since / until: fester Zeitraum als 'YYYY-MM-DD', beide zusammen und
einschließlich (sonst error=date_range_incomplete; until vor since
error=date_range_invalid); hat Vorrang vor date_preset und days.
date_preset: relativer Zeitraum nach Metas Kalender — today, yesterday,
this_month, last_month, this_quarter, last_quarter, this_year,
last_year, last_3d/7d/14d/28d/30d/90d, last_week_mon_sun,
last_week_sun_sat, this_week_mon_today, this_week_sun_today, maximum,
data_maximum (error=invalid_date_preset sonst); hat Vorrang vor days.
Jede Zeile trägt date_start/date_stop — die tatsächlich summierte
Spanne, wie Meta sie meldet (bei daily stattdessen date je Tag).
totals_only: True liefert Gesamtzahlen des Kontos als EINE Zeile (ohne
campaign/campaign_id) — für Kontosummen diesen Weg nehmen und nicht
Zeilen selbst addieren: bei breakdown überschneiden sich reach-Werte.
Mit breakdown/daily kombinierbar; nicht mit campaign_id
(error=totals_only_with_campaign — eine Kampagne liefert mit
campaign_id ohnehin genau eine Zeile).
Zahlen folgen der Attributionseinstellung der Adsets (unified attribution,
wie im Ads Manager) — nicht Metas API-Default.
Liefert neben Impressionen/Spend/Conversions auch link_clicks (echte
Link-Klicks — clicks zählt Likes und Profilaufrufe mit),
landing_page_views und landing_page_rate_pct (wie viele Klicks die Seite
erreichen), reach, frequency, cpm, cpc und cost_per_link_click.
Bei leeren Insights trotz vorhandener Kampagnen kommt stattdessen ein Dict
mit result=[], time_range bzw. date_preset und info-Erklärung zurück.
breakdown: Aufschlüsselung statt Summenzeile — 'publisher_platform'
(Facebook vs. Instagram vs. Audience Network), 'platform_position',
'device_platform', 'age', 'gender', 'country', 'region'.
daily: True liefert eine Zeitreihe je Tag. Ein kürzeres Zeitfenster ersetzt
das NICHT — es summiert nur weniger Tage zu einer Zeile.
campaign_id: nur diese Kampagne. Ohne Angabe ALLE Kampagnen des Kontos.
Eine uebergebene Kampagnen-/Adset-/Ad-ID muss zum Werbekonto des Workspace gehoeren —
IDs eines anderen Kontos (auch wenn die Meta-Verbindung es sieht) → {'error': 'foreign_object'}.
workspace: Slug des Kunden-Workspace (optional bei nur einem Workspace).
conversions zählt AUSSCHLIESSLICH Käufe und Leads. Eigene Custom
Conversions stehen getrennt in custom_conversions, und actions führt
alle Ereignistypen mit Zahlen auf — conversions=0 heißt deshalb nicht
"konvertiert nicht", sondern ist an actions gegenzuprüfen.
Obergrenze rund 2.000 Zeilen. Wird sie erreicht, kommt statt der Liste
ein Objekt mit result und warning zurück; die Sortierung gilt dann
nur für den Ausschnitt.
