/v1/insights
Liefert normalisierte Performance-Metriken (Spend, Impressionen, Reichweite, Klicks, CTR, CPC, CPM, Conversions, Conversion-Wert, ROAS, CPA) je Entity auf Ad-Set- oder Ad-Ebene und Zeitspanne. Geldwerte in Major-Units der Konto-Währung. Daten aus täglichen DB-Snapshots, kein Live-Call zur Meta-API. Die Kampagnen-Ebene ist nicht verfügbar.
Query-Parameter
| Name | Typ | Pflicht | Beschreibung |
|---|---|---|---|
| level | enum | erforderlich | adset oder ad. Ebene der zurückgegebenen Entities. Die Kampagnen-Ebene ist nicht verfügbar. z. B. adset |
| entity_id | string (UUID) | optional | Interne UUID eines Ad-Sets (level=adset) oder einer Ad (level=ad), aus GET /v1/adsets bzw. /v1/ads. Ohne Angabe werden alle Entities der Ebene zurückgegeben. z. B. a1b2c3d4-e5f6-7890-abcd-ef1234567890 |
| adset_id | string (UUID) | optional | Nur mit level=ad: liefert die Metriken aller Ads dieses Ad-Sets. So erreichst du mit der Ad-Set-ID die enthaltenen Ads, ohne deren IDs zu kennen. z. B. a51f9c33-7e2b-4d18-8a0e-6b9c1d4f2e77 |
| date_range | string | object | optional | Preset: today, yesterday, last_3d, last_7d, last_14d, last_28d, last_30d, last_90d, this_month, last_month, this_week_mon_today, last_week_mon_sun, maximum. Oder Objekt {since: "YYYY-MM-DD", until: "YYYY-MM-DD"}. Default: last_30d. z. B. last_30d |
| fields | string (CSV) | optional | Auswahl der Kern-Metriken: spend, impressions, reach, clicks, ctr, cpc, cpm, conversions, conversion_value, roas, cpa. Default: alle. z. B. spend,impressions,clicks,ctr,cpc,roas |
| breakdowns | string (CSV) | optional | Aufschlüsselung nach genau einem gesyncten Set: age, gender, country, publisher_platform, platform_position, impression_device, device_platform oder die Kombination age,gender. Reihenfolge wie angegeben. z. B. age,gender |
Request · Next.js
const res = await fetch(`https://api.campaignkit.ventureon.io/v1/insights?level=adset&entity_id=a1b2c3d4-e5f6-7890-abcd-ef1234567890&adset_id=a51f9c33-7e2b-4d18-8a0e-6b9c1d4f2e77&date_range=last_30d&fields=spend%2Cimpressions%2Cclicks%2Cctr%2Ccpc%2Croas&breakdowns=age%2Cgender`, {
method: "GET",
headers: {
Authorization: `Bearer ${process.env.CAMPAIGNKIT_API_KEY}`,
},
});
const data = await res.json();Response 200
{
"data": [
{
"id": "9f3c1d4f-2e77-4a18-8a0e-6b9c1d4f2e77",
"adset_id": "a51f9c33-7e2b-4d18-8a0e-6b9c1d4f2e77",
"meta_id": "604839271650",
"spend": 1928.00, "impressions": 187400, "reach": 92100,
"clicks": 5082, "ctr": 2.71, "cpc": 0.38, "cpm": 10.29,
"conversions": 246, "conversion_value": 9832.80, "roas": 5.1, "cpa": 7.84
}
]
}level=ad-Antworten enthalten zusätzlich adset_id (zum Gruppieren). Datenfrische: tägliche Snapshots, Conversions werden über ein 7-Tage-Fenster nachträglich aktualisiert (Backfill). Mit breakdowns enthält jede Zeile zusätzlich ein breakdown-Objekt (z. B. {age, gender}). reach ist eine Unique-Metrik und wird NICHT über Tage aufsummiert (das würde Personen mehrfach zählen): bei einem Zeitraum über mehrere Tage ist reach die höchste Einzeltags-Reichweite (belastbare Untergrenze), bei einem einzelnen Tag exakt. Alle übrigen Mengen-Metriken (spend, impressions, clicks, conversions, conversion_value) sind additiv.