Advertiser API von OpenAI Ads: Alle Insights-Felder für Kampagne, Anzeigengruppe und Anzeige

Eine API-Familie, ein Auswertungsbereich

Rund um OpenAI Ads kursieren viele Bezeichnungen, doch offiziell gibt es genau zwei Schnittstellenfamilien: die Conversions API für das Zurückspielen von Abschlüssen und die Advertiser API für Verwaltung und Auswertung von Werbekonten. Insights ist dabei kein eigenständiges Produkt, sondern der Reporting-Bereich innerhalb der Advertiser API. Wer im Team oder gegenüber Kunden sauber kommunizieren will, sollte diese Trennung konsequent verwenden, weil sie auch die Struktur der Dokumentation und der Berechtigungen widerspiegelt.

Praktisch bedeutet das: Ein API-Schlüssel authentifiziert immer genau ein Werbekonto. Das Konto wird aus der Authentifizierung abgeleitet und darf nicht zusätzlich als Parameter mitgeschickt werden. Wer eine Konto-ID mitsendet, erhält eine klare Fehlermeldung mit Statuscode 400. Für Agenturen heißt das, dass pro betreutem Konto ein eigener Schlüssel verwaltet und getrennt gespeichert werden muss – am besten verschlüsselt und ausschließlich serverseitig.

Der zweite wichtige Punkt betrifft die Feldauswahl. Anfragen an Insights arbeiten mit einer expliziten Liste gewünschter Felder. Wird ein Feld angefragt, das auf der jeweiligen Ebene nicht existiert, antwortet die API mit einer Fehlermeldung, die alle erlaubten Feldnamen aufzählt. Diese Antwort ist wertvoll: Sie ist faktisch die aktuellste Feldreferenz für das jeweilige Konto und lässt sich im eigenen Client automatisch auswerten, um unpassende Felder zu verwerfen und die Abfrage sauber zu wiederholen.

Insights ist kein eigenes Produkt, sondern der Auswertungsbereich der Advertiser API – und liefert neben Zahlen auch Titel, Text und Ziellink jeder Anzeige.

Die fünf Endpunkte im Überblick

Der Insights-Bereich stellt fünf Einstiegspunkte bereit. Über GET /ad_account/insights kommen Werte für das gesamte Werbekonto, wahlweise aggregiert auf einer tieferen Ebene. GET /campaigns/{campaign_id}/insights liefert die Werte einer einzelnen Kampagne, GET /ad_groups/{ad_group_id}/insights die einer Anzeigengruppe und GET /ads/{ad_id}/insights die einer einzelnen Anzeige. Conversions laufen abweichend über POST /conversions/insights, weil dort Listen von Entitäts-IDs im Rumpf der Anfrage übergeben werden.

Zwei Parameter steuern die Form der Antwort. Mit aggregation_level wird festgelegt, auf welcher Ebene verdichtet wird: ad_account, campaign, ad_group oder ad. Mit time_granularity wird die zeitliche Auflösung bestimmt: hourly, daily, monthly oder none. Für ein Tagesboard mit Kampagnen in Zeilen und Tagen in Spalten ist die Kombination aus aggregation_level=campaign und time_granularity=daily der Standardfall, ergänzt um das Feld metadata.readable_time als Datumsspalte.

In der Antwort werden verschachtelte Feldnamen flachgezogen. Aus campaign.id wird campaign_id, aus metadata.readable_time wird readable_time und aus product.feed_id wird product_feed_id. Ein robuster Client sollte daher beide Schreibweisen akzeptieren, statt sich auf eine festzulegen. Das erspart Ausfälle, wenn die Plattform Feldnamen ergänzt oder die Darstellung anpasst – und es macht das Speichern in der eigenen Datenbank deutlich verlässlicher.

Kennzahlen: sechs Werte auf jeder Ebene

Auf allen Ebenen stehen dieselben sechs Standardkennzahlen zur Verfügung: impressions, clicks, spend, ctr, cpc und cpm. Sie werden mit dem passenden Präfix angefragt, also etwa campaign.impressions, ad_group.clicks oder ad.spend. Damit lassen sich klassische Effizienzfragen bereits vollständig beantworten: Wie teuer ist ein Klick, wie oft wird eine Anzeige gesehen, und wie verändert sich die Klickrate über die Zeit.

Wichtig ist die Unterscheidung zwischen berechneten und gelieferten Werten. CTR, CPC und CPM kann die Plattform direkt liefern, sie lassen sich aber auch aus Klicks, Impressionen und Spend selbst berechnen. Für eigene Dashboards empfiehlt sich, beide Wege vorzusehen: den gelieferten Wert bevorzugt anzeigen und bei fehlendem Feld auf die eigene Berechnung zurückzufallen. So bleibt das Board auch dann vollständig, wenn ein Konto einzelne Felder nicht zurückgibt.

Ein häufiger Stolperstein sind Nullzeilen. Standardmäßig tauchen Einträge ohne Impressionen nicht in der Antwort auf. Wer eine lückenlose Zeitreihe braucht, kann sie über includes[]=zero_impression_items anfordern. Für Vergleichsansichten mit Vortagesfärbung ist das entscheidend, weil sonst ein Tag ohne Auslieferung schlicht fehlt und die Differenz gegen den falschen Vortag gerechnet wird.

Metadaten: Namen, Status, Budgets und Anzeigentexte

Neben den Kennzahlen liefert Insights beschreibende Felder. Auf Kontoebene sind das ad_account.name, ad_account.url sowie ad_account.budget.daily und ad_account.budget.lifetime. Auf Kampagnenebene kommen campaign.name, campaign.description, campaign.status, campaign.start_time, campaign.end_time und ebenfalls Tages- sowie Laufzeitbudget hinzu. Diese Felder eignen sich hervorragend als Stammdaten, die einmal täglich mitgeschrieben werden und in der eigenen Datenbank historisiert bleiben.

Die Anzeigengruppe bietet ad_group.name, ad_group.description und ad_group.status. Damit lässt sich eine Kampagne in der Oberfläche aufklappen und in ihre Gruppen zerlegen, ohne eine zweite Quelle zu benötigen. Auf Anzeigenebene wird es besonders praktisch: ad.name, ad.title, ad.copy, ad.link, ad.status und ad.review_status liefern nicht nur Zahlen, sondern die eigentliche Kreation samt Freigabestatus und Ziellink.

Damit wird Insights zu mehr als einem Zahlenlieferanten. Wer Titel, Text und Zielseite zusammen mit den Kennzahlen speichert, kann Kreativ-Analysen fahren: Welche Formulierung erzeugt die höhere Klickrate, welche Zielseite bringt teure Klicks, welche Anzeige hängt seit Tagen in der Prüfung. Genau diese Kombination fehlt in vielen selbstgebauten Reports – dabei ist sie nur eine Feldliste entfernt.

Conversions laufen über einen eigenen Endpunkt

Conversions sind bewusst vom übrigen Reporting getrennt. Sie werden per POST /conversions/insights abgefragt, wobei Ebene und die betroffenen Entitäts-IDs im Rumpf übergeben werden. Zurück kommen conversions, click_through_conversions und view_through_conversions. Dabei entsprechen die Conversions den Click-through-Conversions; View-through-Conversions werden ergänzend ausgewiesen und sollten in Berichten nie stillschweigend addiert werden.

Für die Praxis heißt das: Ein vollständiges Tagesboard braucht zwei Abfragen. Zuerst die Kennzahlen über den Insights-Endpunkt, danach die Conversions für dieselben IDs und denselben Zeitraum. Beide Ergebnisse werden über den Schlüssel aus Entitäts-ID und Tag zusammengeführt. Fällt die zweite Abfrage aus, sollte das Board trotzdem funktionieren und die Conversion-Spalten leer lassen, statt eine Fehlermeldung anzuzeigen.

Ob überhaupt Conversions ankommen, hängt am Messaufbau. Ohne korrekt eingebundenes Measurement Pixel oder saubere Übergaben über die Conversions API bleiben die Werte bei null – die Advertiser API erfindet nichts. Wer im Board dauerhaft Striche bei Kosten pro Conversion sieht, prüft deshalb zuerst das Tracking und erst danach die Schnittstelle.

Segmente: Land, Gerät und Produkt

Für tiefere Analysen kennt Insights eine optionale Segmentdimension, angefordert über segments[]. Erlaubt sind country, device und product – aber immer nur eine Dimension pro Abfrage. Wer Land und Gerät gleichzeitig braucht, stellt zwei Anfragen und führt die Ergebnisse lokal zusammen. Für ein Dashboard ist das kein Nachteil, solange die Daten ohnehin täglich in die eigene Datenbank geschrieben werden.

Das Länder-Segment liefert country.name sowie die dazugehörigen Werte country.clicks, country.spend und country.impressions. Das Gerätesegment arbeitet analog mit device.type und den passenden Kennzahlen. Damit lässt sich schnell erkennen, ob ein hoher Klickpreis an einem einzelnen Markt hängt oder ob mobile Auslieferung deutlich anders performt als Desktop – ein Muster, das bei jungen Werbeplattformen erfahrungsgemäß stark schwankt.

Das Produktsegment richtet sich an Feed-getriebene Kampagnen und liefert unter anderem product.feed_id, product.item_id, product.title, product.description, product.target_url, product.image_url, product.brand, product.seller_name, product.price und product.availability. Damit wird aus dem Report faktisch eine Produktanalyse: Welcher Artikel verbrennt Budget, welcher ist gar nicht mehr verfügbar und läuft trotzdem weiter.

Filter, Sortierung, Paging und die Grenzen

Abfragen lassen sich mit filters[] eingrenzen, unterstützt werden unter anderem IN, GREATER_THAN und LESS_THAN. Über sort[] wird die Reihenfolge bestimmt, und Paging erlaubt Antworten bis zu 2000 Zeilen. Für ein Konto mit wenigen Kampagnen spielt das kaum eine Rolle, für Agenturkonten mit vielen Anzeigen über 30 Tage dagegen sehr wohl: Dort muss der eigene Client zwingend seitenweise lesen, sonst fehlen stillschweigend Daten.

Drei Grenzen sollte jedes Team kennen. Erstens ist pro Abfrage nur eine Segmentdimension möglich. Zweitens unterstützt der Conversions-Endpunkt aktuell nur einen Zeitraum je Anfrage. Drittens erlauben segmentierte Abfragen keine stündliche Auflösung; dort stehen none, daily und monthly zur Verfügung. Wer diese Regeln in die eigene Abfragelogik einbaut, spart sich eine ganze Klasse von Fehlermeldungen.

Für die Architektur folgt daraus ein klares Muster: ein serverseitiger Job holt die Daten, schreibt sie idempotent in die eigene Datenbank und aktualisiert dabei die letzten Tage erneut, weil Conversions nachgemeldet werden. Die Oberfläche liest anschließend nur noch lokal. Genau so arbeitet auch unser KPI Board, das Kampagnen, Anzeigengruppen und Anzeigen samt Land- und Geräteaufschlüsselung in einer Tagesansicht zusammenführt.