Schnittstellen

Insights (Advertiser API)

Insights ist kein eigenes Produkt, sondern der Reporting-Endpunkt der Advertiser API. Er liest aggregierte Performance-Daten aus OpenAI Ads – für eigene Dashboards, Tracking-Apps und Agenturreporting.

Was der Insights-Endpunkt liefert

Ein sicherer Server-Job holt die Werte regelmäßig ab und speichert Tageswerte lokal – zusammen mit Kampagnen-, Ad-Group- und Ad-IDs als Stammdaten. Das Frontend liest danach nur noch aus der eigenen Datenbank.

Importiere Spend, Impressions, Clicks und Conversions.
time_granularity und aggregation_level bestimmen die Granularität.
Historie lokal halten, damit Reports unabhängig von API-Limits funktionieren.

curl

curl -sS -G "https://api.ads.openai.com/v1/ad_account/insights" \
  -H "Authorization: Bearer <OPENAI_ADS_API_KEY>" \
  --data-urlencode 'time_granularity=daily' \
  --data-urlencode 'aggregation_level=campaign' \
  --data-urlencode 'fields[]=metadata.readable_time' \
  --data-urlencode 'fields[]=campaign.id' \
  --data-urlencode 'fields[]=campaign.name' \
  --data-urlencode 'fields[]=campaign.impressions' \
  --data-urlencode 'fields[]=campaign.clicks' \
  --data-urlencode 'fields[]=campaign.spend'

<OPENAI_ADS_API_KEY> nur serverseitig speichern (Secrets/Env). Niemals im Browser-Code oder im Tag Manager ablegen. Das Werbekonto ergibt sich aus dem Schlüssel – eine Konto-ID darf nicht mitgesendet werden.

Endpunkte und Ebenen

GET /ad_account/insights – gesamtes Werbekonto
GET /campaigns/{campaign_id}/insights – eine Kampagne
GET /ad_groups/{ad_group_id}/insights – eine Anzeigengruppe
GET /ads/{ad_id}/insights – eine einzelne Anzeige
POST /conversions/insights – Conversions für eine Liste von IDs

aggregation_level kennt ad_account, campaign, ad_group und ad. time_granularity kennt hourly, daily, monthly und none.

Kennzahlen auf jeder Ebene

Auf allen Ebenen stehen dieselben sechs Kennzahlen bereit – jeweils mit passendem Präfix, also etwa campaign.clicks oder ad.spend:

impressions, clicks, spend
ctr, cpc, cpm

Zeilen ohne Impressionen fehlen standardmäßig. Für lückenlose Zeitreihen hilft includes[]=zero_impression_items.

Metadaten je Ebene

Konto: ad_account.name, ad_account.url, ad_account.budget.daily, ad_account.budget.lifetime
Kampagne: campaign.name, campaign.description, campaign.status, campaign.start_time, campaign.end_time, campaign.budget.daily, campaign.budget.lifetime
Anzeigengruppe: ad_group.name, ad_group.description, ad_group.status
Anzeige: ad.name, ad.title, ad.copy, ad.link, ad.status, ad.review_status

Conversions

Conversions laufen über POST /conversions/insights mit Ebene und Entitäts-IDs im Rumpf. Zurück kommen conversions, click_through_conversions und view_through_conversions. Conversions entsprechen den Click-through-Conversions; View-through-Werte werden ergänzend ausgewiesen und sollten nicht einfach addiert werden.

Segmente: Land, Gerät, Produkt

Pro Abfrage ist genau eine Segmentdimension über segments[] erlaubt.

country: country.name, country.clicks, country.spend, country.impressions
device: device.type plus Klicks, Spend und Impressionen
product: product.feed_id, product.item_id, product.title, product.description, product.target_url, product.image_url, product.brand, product.seller_name, product.price, product.availability

Filter, Paging und Grenzen

filters[] mit IN, GREATER_THAN, LESS_THAN; sort[] für die Reihenfolge.
Paging bis 2000 Zeilen je Antwort – bei vielen Anzeigen zwingend umsetzen.
Nur eine Segmentdimension pro Abfrage.
Der Conversions-Endpunkt unterstützt aktuell nur einen Zeitraum pro Anfrage.
Segmentierte Abfragen unterstützen none, daily und monthly, aber kein hourly.
In der Antwort werden Felder flachgezogen: campaign.id → campaign_id.

Typischer Job

Server-Cron ruft täglich die Kennzahlen ab, speichert Tageswerte lokal und hält Kampagnen-IDs als Stammdaten.

Bern · Schweiz

00:00

Weltweit wachsende Community für mehr Klarheit, Benchmarks, Trainingsdaten und die schnellstmögliche Optimierung deines Agenten

Jetzt als AdBase Member registrieren